Update documentation for SRW APP

VERSION

@@ -1 +1 @@
-1.6.0
+1.7.0

docs/source/chgres_cube.rst

@@ -19,17 +19,19 @@ The program assumes Noah/Noah-MP LSM coefficients for certain soil thresholds. I
             * Computes required soil parameters
             * Reads the variable mapping (VARMAP) table.
       * model_grid.F90 - Sets up the ESMF grid objects for the input data grid and target FV3 grid.
-      * static_data.F90 - Reads static surface climatological data for the target FV3 grid (such as soil type and vegetation type).  Time interpolates time-varying fields, such as monthly plant greenness, to the model run time.  Data for each target FV3 resolution resides in the ‘fixed’ directory.  Set path via the fix_dir_target_grid namelist variable.
+      * static_data.F90 - Reads static surface climatological data for the target FV3 grid (such as soil type and vegetation type).  Time interpolates time-varying fields, such as monthly plant greenness, to the model run time. Set path to these files via the fix_dir_target_grid namelist variable.
       * write_data.F90 - Writes the tiled and header files expected by the forecast model.
       * input_data.F90 - Contains routines to read atmospheric and surface data from GRIB2, NEMSIO and NetCDF files.
-      * utils.f90 - Contains utility routines, such as error handling.
+      * utils.F90 - Contains utility routines, such as error handling.
       * grib2_util.F90 -  Routines to (1) convert from RH to specific humidity; (2) convert from omega to dzdt.  Required for GRIB2 input data.
       * atmosphere.F90 - Process atmospheric fields.  Horizontally interpolate from input to target FV3 grid using ESMF regridding.  Adjust surface pressure according to terrain differences between input and target grid.  Vertically interpolate to target FV3 grid vertical levels.  Description of main routines:
 
             * read_vcoord_info - Reads model vertical coordinate definition file (as specified by namelist variable vcoord_file_target_grid).
-            * newps - computes adjusted surface pressure given a new terrain height.
-            * newpr1 - computes 3-D pressure given an adjusted surface pressure.
+            * newps - Computes adjusted surface pressure given a new terrain height.
+            * newpr1 - Computes 3-D pressure given an adjusted surface pressure.
             * vintg - vertically interpolate atmospheric fields to target FV3 grid.
+            * vintg_wam - vertically interpolate atmospheric fields to the thermosphere. Supports the Whole Atmosphere Model.
+      * atmosphere_target_data.F90 - Holds the target grid atmospheric ESMF fields.
       * surface.F90 - process land, sea/lake ice, open water/Near Sea Surface Temperature (NSST) fields.  NSST fields are not available when using GRIB2 input data.  Description of main routines:
 
             * interp - horizontally interpolate fields from input to target FV3 grid.
@@ -38,7 +40,10 @@ The program assumes Noah/Noah-MP LSM coefficients for certain soil thresholds. I
             * rescale_soil_moisture - adjust total soil moisture for differences between soil type on input and target FV3 grids.  Required to preserve latent/sensible heat fluxes.
             * roughness - set roughness length at land and sea/lake ice.  At land, a vegetation type-based lookup table is used.
             * qc_check - some consistency checks.
-      * search_util.f90 - searches for the nearest valid land/non-land data where the input and target fv3 land-mask differ.  Example: when the target FV3 grid depicts an island that is not resolved by the input data.  If nearby valid data is not found, a default value is used.
+      * surface_target_data.F90 - Holds the target grid surface ESMF fields.
+      * search_util.F90 - searches for the nearest valid land/non-land data where the input and target fv3 land-mask differ.  Example: when the target FV3 grid depicts an island that is not resolved by the input data.  If nearby valid data is not found, a default value is used.
+      * thompson_mp_climo_data.F90 - Processes climatological Thompson micro-physics fields.
+      * wam_climo_data.f90 - Process vertical profile climatological data for the Whole Atmosphere Model.
 
 Configuring and using chgres_cube for global applications
 ---------------------------------------------------------
@@ -48,7 +53,7 @@ Program inputs and outputs for global applications
 
 **Inputs**
 
-The following four sets of files are located here: https://ftp.emc.ncep.noaa.gov/EIB/UFS/global/fix/fix_fv3_gmted2010.v20191213/
+Users may create their own global grids, or use the pre-defined files are located `here <https://ftp.emc.ncep.noaa.gov/EIB/UFS/global/fix/fix_fv3_gmted2010.v20191213/>`_.
 
       * FV3 mosaic file - (NetCDF format)
 	      * CRES_mosaic.nc
@@ -69,7 +74,7 @@ The following four sets of files are located here: https://ftp.emc.ncep.noaa.gov
 	      * CRES_oro_data.tile5.nc
 	      * CRES_oro_data.tile6.nc
 
-      * FV3 surface climatological files - Located under the ./fix_sfc sub-directory.  One file for each tile.  NetCDF format.
+      * FV3 surface climatological files - Located under the `./fix_sfc <https://ftp.emc.ncep.noaa.gov/EIB/UFS/global/fix/fix_fv3_gmted2010.v20191213/C48/fix_sfc>`_ sub-directory.  One file for each tile.  NetCDF format.
 	      * CRES.facsf.tileX.nc (fractional coverage for strong/weak zenith angle dependent albedo)
 	      * CRES.maximum_snow_albedo.tileX.nc (maximum snow albedo)
 	      * CRES.slope_type.tileX.nc (slope type)
@@ -79,7 +84,7 @@ The following four sets of files are located here: https://ftp.emc.ncep.noaa.gov
 	      * CRES.vegetation_greenness.tileX.nc (vegetation greenness)
 	      * CRES.vegetation_type.tileX.nc (vegetation type)
 
-      * FV3 vertical coordinate file.  Text file.  Located here: https://ftp.emc.ncep.noaa.gov/EIB/UFS/global/fix/fix_am.v20191213/
+      * FV3 vertical coordinate file.  Text file.  `Located here <https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#fix/fix_am/>`_.
 	      * global_hyblev.l$LEVS.txt
 
       * Input data files.  GRIB2, NEMSIO or NetCDF.  See the next section for how to find this data.
@@ -103,24 +108,20 @@ The following four sets of files are located here: https://ftp.emc.ncep.noaa.gov
 	      * out.sfc.tile1.nc
 
 
-Where to find GFS GRIB2, NEMSIO and NetCDF data for global applications
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Where to find GFS GRIB2 and NetCDF data for global applications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 **GRIB2**
 
-      * 0.25-degree data (last 10 days only) - Use the **gfs.tHHz.pgrb2.0p25.f000** files in subdirectory gfs.YYYYMMDD/HH `here <https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod>`_.`
+      * 0.25-degree data (last 10 days only) - Use the **gfs.tHHz.pgrb2.0p25.f000** files in subdirectory ./gfs.YYYYMMDD/HH/atmos on `NOMADS <https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod>`_.
 
-      * 0.5-degree data - Use the **gfs_4_YYYYMMDD_00HH_000.grb2** file, under **GFS Forecasts 004 (0.5-deg)** here: `NCDC - Global Forecast System <https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/global-forcast-system-gfs>`__.  Note: *Tests were not done with the AVN, MRF or analysis data*.
+      * 0.5-degree data - Use the **gfs_4_YYYYMMDD_HHHH_000.grb2** file, under **GFS Forecasts 004 (0.5-deg)** here: `NCEI - Global Forecast System <https://www.ncei.noaa.gov/products/weather-climate-models/global-forecast>`_.  Note: *Tests were not done with the AVN, MRF or analysis data*.
 
-      * 1.0-degree data - Use the **gfs_3_YYYYMMDD_00HH_000.grb2 file**, under **GFS Forecasts 003 (1-deg)** here: `NCDC - Global Forecast System <https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/global-forcast-system-gfs>`__.  Note: *Tests were not done with the AVN, MRF or analysis data*.
-
-**NEMSIO**
-
-      * T1534 gaussian (last 10 days only) - Use the **gfs.tHHz.atmanl.nemsio** (atmospheric fields) and **gfs.tHHz.sfcanl.nemsio** (surface fields) files in subdirectory gfs.YYYYMMDD/HH `here <https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod>`_.
+      * 1.0-degree data - Use the **gfs_3_YYYYMMDD_HHHH_000.grb2 file**, under **GFS Forecasts 003 (1.0-deg)** here: `NCEI - Global Forecast System <https://www.ncei.noaa.gov/products/weather-climate-models/global-forecast>`_.  Note: *Tests were not done with the AVN, MRF or analysis data*.
 
 **NetCDF**
 
-      * T1534 gaussian (don't have any more details at this time).
+      * T1534 gaussian (last 10 days only) - Use the **gfs.tHHz.atmanl.nc** (atmospheric fields) and **gfs.tHHz.sfcanl.nc** (surface fields) files in subdirectory ./gfs.YYYYMMDD/HH/atmos on `NOMADS <https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod>`_.
 
 Initializing global domains with GRIB2 data - some caveats
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -235,7 +236,7 @@ The following four sets of files/directories should all be located in the same d
 	      * CRES.vegetation_greenness.tile7.halo4.nc (vegetation greenness)
 	      * CRES.vegetation_type.tile7.halo4.nc (vegetation type)
 
-      * FV3 vertical coordinate file.  Text file. Located in ./fix_am directory.
+      * FV3 vertical coordinate file.  Text file.  `Located here <https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#fix/fix_am/>`_.
 	      * global_hyblev.l$LEVS.txt
 
       * Input data files. GRIB2 only.  See the next section for how to find this data.
@@ -253,23 +254,23 @@ Where to find FV3GFS, NAM, HRRR, and RAP GRIB2 data for regional applications
 
 **FV3GFS**
 
-      * 0.25-degree data (last 10 days only) - Use the **gfs.tHHz.pgrb2.0p25.f000** files in subdirectory gfs.YYYYMMDD/HH `here <https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod>`_.
+      * 0.25-degree data (last 10 days only) - Use the **gfs.tHHz.pgrb2.0p25.f000** files in subdirectory ./gfs.YYYYMMDD/HH/atmos on `NOMADS <https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod>`_.
 
-      * 0.5-degree data - Use the **gfs_4_YYYYMMDD_00HH_000.grb2** file, under **GFS Forecasts 004 (0.5-deg)** here: `NCDC - Global Forecast System <https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/global-forcast-system-gfs>`__.  Note: *Tests were not done with the AVN, MRF or analysis data*.
+      * 0.5-degree data - Use the **gfs_4_YYYYMMDD_HHHH_000.grb2** file, under **GFS Forecasts 004 (0.5-deg)** here: `NCEI - Global Forecast System <https://www.ncei.noaa.gov/products/weather-climate-models/global-forecast>`_.  Note: *Tests were not done with the AVN, MRF or analysis data*.
 
-      * 1.0-degree data - Use the **gfs_3_YYYYMMDD_00HH_000.grb2 file**, under **GFS Forecasts 003 (1-deg)** here: `NCDC - Global Forecast System <https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/global-forcast-system-gfs>`__.  Note: *Tests were not done with the AVN, MRF or analysis data*.
+      * 1.0-degree data - Use the **gfs_3_YYYYMMDD_HHHH_000.grb2 file**, under **GFS Forecasts 003 (1.0-deg)** here: `NCEI - Global Forecast System <https://www.ncei.noaa.gov/products/weather-climate-models/global-forecast>`_.  Note: *Tests were not done with the AVN, MRF or analysis data*.
 
 **NAM**
 
-     * 12-km data from last few days (NOMADS) - Use the **nam.tHHz.conusnest.hiresfFH.tmHH.grib2** files in subdirectory nam.YYYYMMDD `here <https://nomads.ncep.noaa.gov/pub/data/nccf/com/nam/prod/>`__.
+     * 12-km data from last few days (NOMADS) - Use the **nam.tHHz.conusnest.hiresfHH.tmHH.grib2** files in subdirectory nam.YYYYMMDD on `NOMADS <https://nomads.ncep.noaa.gov/pub/data/nccf/com/nam/prod/>`_.
 
-     * 12-km data from previous 6 months - Use the **nam_218_YYYYMMDD_00HH_000.grb2 file**,   under **NAM Forecasts NAM-NMM 218 (12km) Domain** here: `NCDC - North American Mesoscale Forecast System <https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/north-american-mesoscale-forecast-system-nam>`__.
+     * 12-km data starting 2020 - Use the **nam_218_YYYYMMDD_HHHH_000.grb2 file**, under **NAM Forecasts NAM-NMM 218 (12km) Domain** here: `NCEI - North American Mesoscale Forecast System <https://www.ncei.noaa.gov/products/weather-climate-models/north-american-mesoscale>`_.
 
-     * 12-km archived data older than 6 months can be requested through the Archive Information Request System `here <https://www.ncdc.noaa.gov/has/HAS.FileAppRouter?datasetname=NAM218&subqueryby=STATION&applname=&outdest=FILE>`__.
+     * 12-km archived data prior to 2020 can be requested through the Archive Information Request System `here <https://www.ncei.noaa.gov/has/HAS.FileAppRouter?datasetname=NAM218&subqueryby=STATION&applname=&outdest=FILE>`_.
 
 **HRRR**
 
-      * 3-km operational data from previous few days (NOMADS) - Use the **hrrr.tHHz.wrfnatfFH.grib2** files in the subdirectory hrrr.YYYYMMDD/conus `here <https://nomads.ncep.noaa.gov/pub/data/nccf/com/hrrr/prod/>`__.
+      * 3-km operational data from previous few days (NOMADS) - Use the **hrrr.tHHz.wrfnatfHH.grib2** files in the subdirectory ./hrrr.YYYYMMDD/conus `here <https://nomads.ncep.noaa.gov/pub/data/nccf/com/hrrr/prod/>`_.
 
       * 3-km operational data from 2015 to present (AWS S3): Go `here <https://registry.opendata.aws/noaa-hrrr-pds/>`__ and click “Browse Bucket.” Type "YYYYMMDD" in to the Search bar. Use the **hrrr.t00z.wrfnatf00.grib2** files in the directory hrrr.YYYYMMDD/conus/.
 
@@ -279,13 +280,11 @@ Where to find FV3GFS, NAM, HRRR, and RAP GRIB2 data for regional applications
 
 **RAP**
 
+      * 13-km operational data for the previous few days (NOMADS): Use the **rap.tHHz.wrfnatfHH.grib2** files in the subdirectory ./rap.YYYYMMDD `here <https://nomads.ncep.noaa.gov/pub/data/nccf/com/rap/prod/>`_.
 
-      * 13-km operational data for the previous few days (NOMADS): Use the **rap.tHHz.wrfnatfFH.grib2** files in the subdirectory rap.YYYYMMDD `here <https://nomads.ncep.noaa.gov/pub/data/nccf/com/rap/prod/>`__.
-
-      * 13-km isobaric level data from previous 6 months : Use the **rap_130_YYYYMMDD_00HH_0FF.grb2** files from the HTTPS option under **RAP Forecasts - RAP 130 (13km) - Domain** at NCEI `here <https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/rapid-refresh-rap>`__.
-
-      * 13-km archived isobaric data older than 6 months can be requested through the Archive Information Request System `here <https://www.ncdc.noaa.gov/has/HAS.FileAppRouter?datasetname=RAP130&subqueryby=STATION&applname=&outdest=FILE>`__.
+      * 13-km isobaric level data from previous 6 months : Use the **rap_130_YYYYMMDD_HHHH_0FF.grb2** files from **RAP Forecasts - RAP 130 (13km) - Domain** at NCEI `here <https://www.ncei.noaa.gov/products/weather-climate-models/rapid-refresh-update>`_.
 
+      * 13-km archived isobaric data older than 6 months can be requested through the Archive Information Request System `here <https://www.ncei.noaa.gov/has/HAS.FileAppRouter?datasetname=RAP130&subqueryby=STATION&applname=&outdest=FILE>`_.
 
 
 Initializing regional domains with GRIB2 data - some caveats
@@ -312,7 +311,6 @@ Namelist variables with “input” in their name refer to data input to chgres_
 **Required Entries**
 
       * fix_dir_target_grid - Path to the FV3-LAM surface climatological files (such as albedo).
-      * fix_dir_input_grid - Directory containing RAP lat/lon file. On NOAA HPC machines, typically the “fix/fix_am” directory of the UFS_UTILS directory. 
       * mosaic_file_target_grid - Path and name of the FV3-LAM mosaic file.
       * orog_dir_target_grid - Directory containing the FV3-LAM orography and grid files (NetCDF).
       * orog_files_target_grid - Names of the FV3-LAM orography file.
@@ -344,6 +342,9 @@ Namelist variables with “input” in their name refer to data input to chgres_
       * minmax_vgfrc_from_climo - Use min/max vegetation fraction from climatology. Valid options: .true. or .false. (Default: .true.)
       * tg3_from_soil - Use tg3 from input soil. Valid options: .true. or .false. . Default: .false.
       * thomp_mp_climo_file - Location of Thompson aerosol climatology file. Provide only if you wish to use these aerosol variables.
+      * wam_cold_start - Cold start for the Whole Atmosphere Model. Valid Options: .true. or .false. (Default: .false.)
+      * use_rh - Use relative humidity instead of specific humidity when reading in external model grib2 files (Default: .false.)
+      * calrh - Type of relative humidity to specific humidity calculation to use (Default: 0; use existing calculation, or 1; use calculation consistent with GFSv15/v16)
 
 Variable Mapping (VARMAP) table
 -------------------------------
@@ -382,7 +383,7 @@ Column 2: Name of the variable in the output “coldstart” files. Unimplemente
 Column 3: Behavior when the code can't find the variable in the input file. Options are:
 
       * "skip": Don't write to the output file.
-      * "intrp": LnP interpolation to missing levels. No extrapolation allowd.
+      * "intrp": Ln(pressure) interpolation to missing levels. Linear interpolation and extrapolation are possible, but require modifying the value of "LINLOG" in input_data.F90 to anything other than 2, or to a negative number, respectively.
       * "set_to_fill": Set to user-specified field value (see column 4).
       * "stop": Force an exception and stop code execution. Use this if you absolutely require a field to be present.