[develop] Updates to Users Guide and Tables

README.md

@@ -63,16 +63,22 @@ Code Managers: Wen Meng, Huiya Chuang, Kate Fossell
 
 ## Prerequisites
 
-The UPP requires certain NCEPLIB packages to be installed via
-the HPC-Stack project.  
+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/.
+The `UPP/modulefiles` directory indicates which package versions are 
+used and supported on Level 1 systems. 
+
+Required NCEPLIBS packages:
 
 - [NCEPLIBS-g2](https://github.com/NOAA-EMC/NCEPLIBS-g2)
 - [NCEPLIBS-g2tmpl](https://github.com/NOAA-EMC/NCEPLIBS-g2tmpl)
 - [NCEPLIBS-sp](https://github.com/NOAA-EMC/NCEPLIBS-sp)
 - [NCEPLIBS-ip](https://github.com/NOAA-EMC/NCEPLIBS-ip)
 - [NCEPLIBS-bacio](https://github.com/NOAA-EMC/NCEPLIBS-bacio)
 - [NCEPLIBS-w3emc](https://github.com/NOAA-EMC/NCEPLIBS-w3emc)
-- [NCEPLIBS-w3nco](https://github.com/NOAA-EMC/NCEPLIBS-w3nco)
 - [CRTM](https://github.com/noaa-emc/emc_crtm)
 
 Also required to build NCEPpost executable (cmake option
@@ -89,11 +95,13 @@ option BUILD_WITH_WRFIO).
 
 The following third-party libraries are required:
 
+- [netcdf](https://github.com/Unidata/netcdf)
 - [netcdf-c](https://github.com/Unidata/netcdf-c)
 - [netcdf-fortran](https://github.com/Unidata/netcdf-fortran)
 - [Jasper](https://github.com/jasper-software/jasper)
 - [libpng](http://www.libpng.org/pub/png/libpng.html)
-- [libz](https://zlib.net/)
+- [zlib](https://zlib.net/)
+- [hdf5](https://github.com/HDFGroup/hdf5)
 
 ## Building
 
@@ -128,3 +136,7 @@ Commerce. The Department of Commerce seal and logo, or the seal and
 logo of a DOC bureau, shall not be used in any manner to imply
 endorsement of any commercial product or activity by DOC or the United
 States Government.
+
+## UPP Terms of Use Notice
+
+The UPP Terms of Use Notice is available at: https://github.com/NOAA-EMC/UPP/wiki/UPP-Terms-of-Use-Notice

docs/Acknowledgments.rst

@@ -6,16 +6,16 @@ The adaptation of the original WRF Post Processor package and Users Guide (by Mi
 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
+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).
 
-Acknowledgement
+**Acknowledging the UPP Team:**
 
 If significant help was provided via the UPP helpdesk for work resulting in a publication, please
-acknowledge the Developmental Testbed Center UPP Team.
+acknowledge the Earth Prediction Innovation Center UPP Team.
 
 For referencing this document please use:
 
-UPP Users Guide V10.1.0, 24 pp.
+UPP Users Guide V11.0.0, 24 pp.

docs/CodeOverview.rst

@@ -1,37 +1,132 @@
-*************
-Code Overview
-*************
-
-The UPP is used to post-process model forecasts and provides the capability to compute a variety of
-diagnostic fields and interpolate to pressure levels or other vertical coordinates.
-
-The 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
-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 <https://www.nco.ncep.noaa.gov/pmb/docs/grib2/>`_ format and can be used directly by
-visualization, plotting, or verification packages, or for further downstream post-processing, e.g.
-statistical post-processing techniques.
-
-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
-- Precipitation-related fields
-- PBL-related fields
-- Severe weather products (e.g. CAPE, Vorticity, Wind shear)
-- Radiative/Surface fluxes
-- 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`.
-
-The UPP has 2D decomposition capabilities (V11.0.0) and is also backwards compatible for 1D decomposition.
+.. role:: underline
+    :class: underline
+.. role:: bolditalic
+    :class: bolditalic
+
+*******************
+Technical Overview
+*******************
+
+The Unified Post Processor (UPP) is used to post-process model forecasts. 
+It can compute a variety of diagnostic fields and interpolate output from the model's 
+native grids to National Weather Service (:term:`NWS`) standard levels (e.g., pressure, height) 
+and standard output grids (e.g., AWIPS, Lambert Conformal, polar-stereographic) in NWS 
+and World Meteorological Organization (WMO) `GRIB2 <https://www.nco.ncep.noaa.gov/pmb/docs/grib2/>`__ format. 
+There is also an option to output fields on the model's native vertical levels. 
+Output from the UPP can be used directly by visualization, plotting, or verification packages 
+or used in further downstream post-processing (e.g., statistical post-processing techniques).
+
+**HIGHLIGHTS**
+
+The UPP reads and processes :term:`GFS` and :term:`LAM` (Limited Area Model) data from the :term:`FV3` :term:`dynamical core` 
+and generates output in :term:`GRIB2` format. It uses :term:`MPI` parallel code and produces hundreds of 
+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
+   - Precipitation-related fields
+   - PBL-related fields
+   - Severe weather products (e.g. CAPE, Vorticity, Wind shear)
+   - Radiative/Surface fluxes
+   - 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`.
+
+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
 feature is available for standalone UPP applications.
 
-Support for the community UPP is provided through `GitHub Discussions <https://github.com/NOAA-EMC/UPP/discussions>`_.
+Support for the community UPP is provided through `GitHub Discussions <https://github.com/NOAA-EMC/UPP/discussions>`__.
+
+**SYNTHETIC SATELLITE PRODUCTS**
+
+The UPP also incorporates the Joint Center for Satellite Data Assimilation (:term:`JCSDA`) Community Radiative
+Transfer Model (:term:`CRTM`) to compute model-derived brightness temperature (TB) for various instruments and
+channels. 
+This additional feature enables the generation of simulated satellite products such as:
+
+   * Geostationary Operational Environmental Satellite (GOES)
+   * Advanced Microwave Scanning Radiometer (AMSRE)
+   * Special Sensor Microwave Imager/Sounder (SSMIS)
+
+For CRTM documentation, refer to the `CRTM User Guide <https://github.com/JCSDA/crtm/wiki/files/CRTM_User_Guide.pdf>`__. 
+
+==============================
+System Architecture Overview
+==============================
+
+The basic components of the :term:`offline UPP` are shown in the schematic below. 
+
+.. figure:: https://raw.githubusercontent.com/wiki/NOAA-EMC/UPP/UPP_schematic.png
+   :width: 75%
+   :alt: The model output files are used as input to the UPP executable. The UPP executable uses the parameter files to determine the list of output fields. The executable generates post-processed output files in grib2 format, which can be used in downstream applications for regridding, visualization, verification, etc. 
+
+The ``upp.x`` component performs the bulk of the post-processing. Its functions include:
+
+   * Vertical interpolation from model levels/surfaces to isobaric, height, and other levels/surfaces
+   * Computing diagnostics from model data such as CAPE, relative humidity, radar reflectivities, etc.
+
+========================
+UPP Directory Structure
+========================
+
+The main UPP repository is named ``UPP``; it is available on GitHub at https://github.com/NOAA-EMC/UPP. 
+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
+
+     | **modulefiles**: Contains modulefiles for specific platforms and compilers for building on
+       pre-configured machines.
+
+     | **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`)
+
+     | **sorc**: Contains source code for:
+     |   - **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
+
+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. 
+
+.. code-block:: console
+
+   UPP      
+    ├── ci                          -------- Automated testing files
+    ├── cmake                       -------- CMake build files
+    ├── docs                        -------- User's Guide files
+    │   └── Doxyfile.in             -------- Doxygen configuration file
+    ├── exec*
+    ├── fix
+    ├── jobs                        -------- Scripts that set up the environment and call ex-scripts from the scripts directory
+    ├── modulefiles
+    ├── parm
+    │    ├── post_avblflds.xml      -------- List of all fields available in UPP
+    │    ├── postcntrl*.xml         -------- User-editable control files that list the variables to be output
+    │    └── postxconfig-NT-*.txt   -------- Text file of requested output that UPP reads (processed from postcntrl)
+    ├── scripts
+    │    └── run_upp                -------- Script that runs the stand-alone UPP package (upp.x)
+    ├── sorc
+    │    ├── libIFI.fd              -------- Private repository (submodule) for in-flight icing
+    │    └── ncep_post.fd           -------- Main post-processing routines
+    ├── tests
+    │    ├── build*
+    │    ├── install*
+    │    └── compile_upp.sh         -------- UPP build script
+    ├── ush                         -------- Utility scripts (referenced & run in /scripts)
+    ├── CMakeLists.txt
+    ├── LICENSE.md
+    ├── README.md
+    └── VERSION 
+
+
+