Update documentation to support SRW APP v2.0

GeorgeGayno-NOAA commented 2 years ago

The 'read the docs' documentation needs to be updated.

chgres_cube now supports the WAM - new namelist option, etc.
sfc_climo_gen now supports VIIRS-based vegetation type data.
chgres_cube - varmap table changes. See #556.
chgres_cube - new GRIB2 humidity processing (new routines "use_rh" and "calrh"). #566
orog_gsl - new orography generation program that outputs fields for the GSL GWD.
vcoord_gen.fd - new utility to generate user-defined hybrid levels.
New programs inland.fd and lake.fd.

GeorgeGayno-NOAA commented 2 years ago

@mdtoy We will need you help to document the 'orog_gsl' program.

mdtoy commented 2 years ago

Sounds good. Let me know how I can help.

On Apr 20, 2022, at 7:41 AM, GeorgeGayno-NOAA @. @.>> wrote:

@mdtoy https://github.com/mdtoy We will need you help to document the 'orog_gsl' program.

— Reply to this email directly, view it on GitHub https://github.com/ufs-community/UFS_UTILS/issues/643#issuecomment-1103947464, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFMODLF6GHM67QJXUBFQJ3TVGACRTANCNFSM5T4CQGNA. You are receiving this because you were mentioned.

GeorgeGayno-NOAA commented 2 years ago

Sounds good. Let me know how I can help.

We need basic information about the program. Its purpose, inputs/outputs etc. You can use the description of the older orog program as a guide: https://georgegayno-noaaufs-utils.readthedocs.io/en/feature-srw_doc/ufs_utils.html#orog

You can add your information to this issue, or use a google doc and link to it. I will add the information to my branch, then create the updated 'readthedocs'.

mdtoy commented 2 years ago

Here is a description of the "orog_gsl” code:

This code creates orographic statistics fields required for the orographic drag suite developed by NOAA's Global Systems Laboratory (GSL). The fields are a subset of the ones calculated by "orog.fd" except that they are calculated in a different manner. The fields are: stddev -- standard deviation of subgrid topography convexity -- convexity of subgrid topography oa1,oa2,oa3,oa4 -- orographic asymmetry of subgrid topography (for 4 orientations: 1-westerly, 2-southerly, 3-southwesterly, 4-northwesterly) ol1,ol2,ol3,ol4 -- orographic effective length of subgrid topography (for 4 orientations: 1-westerly, 2-southerly, 3-southwesterly, 4-northwesterly)

Two Cxxx_oro_data files are created:

an "ls" (large-scale) file for the gravity wave drag and blocking schemes of Kim and Doyle (QJRMS, 2005)
a "ss" (small-scale) file for the small-scale gravity wave drag scheme of Tsiringakis et al. (QJRMS, 2017) and the turbulent orographic form drag (TOFD) scheme of Beljaars et al. (QJRMS, 2004)

The inputs to be passed to the executable are tile number (1-6 for global, 7 for stand-alone regional) and grid resolution, e.g., 768 for C768.

The source data are the following two files to be located in the "fix" directory:

geo_em.d01.lat-lon.2.5m.HGT_M.nc -- global topographic data on 2.5-minute lat-lon grid (interpolated from GMTED2010 30-second topographic data)
HGT.Beljaars_filtered.lat-lon.30s_res.nc -- global topographic data on 30-second lat-lon grid (GMTED2010 data smoothed according to Beljaars et al. (QJRMS, 2004))

On Apr 20, 2022, at 9:13 AM, GeorgeGayno-NOAA @.***> wrote:

Sounds good. Let me know how I can help.

We need basic information about the program. Its purpose, inputs/outputs etc. You can use the description of the older orog program as a guide: https://georgegayno-noaaufs-utils.readthedocs.io/en/feature-srw_doc/ufs_utils.html#orog https://georgegayno-noaaufs-utils.readthedocs.io/en/feature-srw_doc/ufs_utils.html#orog You can add your information to this issue, or use a google doc and link to it. I will add the information to my branch, then create the updated 'readthedocs'.

— Reply to this email directly, view it on GitHub https://github.com/ufs-community/UFS_UTILS/issues/643#issuecomment-1104050247, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFMODLHAYJSCNQCJIQTA7R3VGANJBANCNFSM5T4CQGNA. You are receiving this because you were mentioned.

GeorgeGayno-NOAA commented 2 years ago

I updated the sfc_climo_gen part. Where will the community access the input climo files? Currently, I refer to the link in the fix directory (./fix/fix_sfc_climo): https://georgegayno-noaaufs-utils.readthedocs.io/en/feature-srw_doc/ufs_utils.html#id30

Here? https://ftp.emc.ncep.noaa.gov/static_files/public/UFS/GFS/fix_nco_gfsv16/fix_sfc_climo/

JeffBeck-NOAA commented 2 years ago

@GeorgeGayno-NOAA, thanks! For those not on NOAA HPC, the documentation points the user to the AWS instance of the fixed files here. Do any of the sfc_climo_gen files need to be updated? I didn't think so.

GeorgeGayno-NOAA commented 2 years ago

@mdtoy Is this Ok? https://georgegayno-noaaufs-utils.readthedocs.io/en/feature-srw_doc/ufs_utils.html#orog-gsl

mdtoy commented 2 years ago

Yes, this looks good. Thank you.

On Apr 20, 2022, at 2:21 PM, GeorgeGayno-NOAA @.***> wrote:

@mdtoy https://github.com/mdtoy Is this Ok? https://georgegayno-noaaufs-utils.readthedocs.io/en/feature-srw_doc/ufs_utils.html#orog-gsl https://georgegayno-noaaufs-utils.readthedocs.io/en/feature-srw_doc/ufs_utils.html#orog-gsl — Reply to this email directly, view it on GitHub https://github.com/ufs-community/UFS_UTILS/issues/643#issuecomment-1104422863, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFMODLBL23ZW3TZAJS3SIW3VGBRONANCNFSM5T4CQGNA. You are receiving this because you were mentioned.

GeorgeGayno-NOAA commented 2 years ago

I think my part is (mostly) finished. Here it is: https://georgegayno-noaaufs-utils.readthedocs.io/en/feature-srw_doc/index.html

There are a few links I am unsure of. Will there be a new directory (v2p0) for the fix data? https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/fix/

And some data, such as the VIIRS vegetation data will need to be hosted there.

JeffBeck-NOAA commented 2 years ago

Thanks, @GeorgeGayno-NOAA! I'm unsure whether EPIC plans to use the EMC FTP website and/or the cloud to stage fixed files/external model data for the v2 release. @mark-a-potts, could you comment on this? Thanks!

GeorgeGayno-NOAA commented 2 years ago

There is an issue open for hosting the fixed data: https://github.com/ufs-community/regional_workflow/issues/716

JeffBeck-NOAA commented 2 years ago

@GeorgeGayno-NOAA, is it just the VIIRS climo data that are new? If so, have those been propagated across HPC platforms? @mkavulich recently tarred up fixed files for the SRW App v2 release and is providing them to @CSyl to stage online, so I'm wondering if they were already included?

GeorgeGayno-NOAA commented 2 years ago

@GeorgeGayno-NOAA, is it just the VIIRS climo data that are new? If so, have those been propagated across HPC platforms? @mkavulich recently tarred up fixed files for the SRW App v2 release and is providing them to @CSyl to stage online, so I'm wondering if they were already included?

Yes, the VIIRS data is hosted on all officially supported machines under the ./fix/fix_sfc_climo directory.

Other new files:

The orog_gsl program (which creates the GSL GWD fields) uses two input files - "geo_em.d01.lat-lon.2.5m.HGT_M.nc" and "HGT.Beljaars_filtered.lat-lon.30s_res.nc". These are located under ./fix/fix_am. (I am not sure why these were not placed under ./fix/fix_orog).
The lake_frac program uses 'GlobalLakeStatus' and 'GlobalLakeDepth'. These are in the ./fix/fix_orog program.

JeffBeck-NOAA commented 2 years ago

@GeorgeGayno-NOAA, thanks. I believe the orography, sfc_climo, and lake_frac fixed files are already in the tarball that @mkavulich put together. Mike, can you confirm?

For the orog_gsl fixed files, we should get those moved to fix_orog.

GeorgeGayno-NOAA commented 2 years ago

@JeffBeck-NOAA and @LarissaReames-NOAA - do you want me to add your documentation updates to my branch? Or do you want to open your own branch?

JeffBeck-NOAA commented 2 years ago

@JeffBeck-NOAA and @LarissaReames-NOAA - do you want me to add your documentation updates to my branch? Or do you want to open your own branch?

@GeorgeGayno-NOAA, I think we can add it to your branch, but it's not quite ready. We'll need to finalize those changes soon. Thanks!

GeorgeGayno-NOAA commented 2 years ago

We now have a way to host the doxygen for multiple tags and releases. See #610.

GeorgeGayno-NOAA commented 2 years ago

Is this where the 'fixed' data will reside? https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#fix/

ufs-community / UFS_UTILS

Update documentation to support SRW APP v2.0 #643