add use_rh and calrh for grib2 humidity processing

[JiliDong-NOAA]

This PR is to add two namelist entries and additional rh to spfh calculation for GFSv15/16 grib2:

"use_rh": if using rh or spfh in grib2 files for humidity (False: use spfh if existing. True: use RH no matter spfh exists or not. Default is False)

"calrh": which rh to spfh calculation will be used. ( = 0 as default to use the current calculation, =1 to use calculation consistent with GFSv15/16).

When setting these two parameters as default (or not specified in namelist), the regression tests won't change.

Related to #565

[JiliDong-NOAA]

@GeorgeGayno-NOAA Not sure how to fix the Doxygen warning to pass check tests:

/home/runner/work/UFS_UTILS/UFS_UTILS/ufs_utils/sorc/chgres_cube.fd/grib2_util.F90:147: error: argument 'fpvsnew' of command @param is not found in the argument list of grib2_util::fpvsnew(real, intent(in) t) (warning treated as error, aborting now)

fpvsnew is a function to calculate saturation water vapor pressure. And I have:

!> Compute saturation vapor pressure
!!
!! @param[out] fpvsnew saturation vapor pressure in Pascals
!! @param[in] t temperature in Kelvin
!! @author N Phillips

[JiliDong-NOAA]

@GeorgeGayno-NOAA Not sure how to fix the Doxygen warning to pass check tests:

/home/runner/work/UFS_UTILS/UFS_UTILS/ufs_utils/sorc/chgres_cube.fd/grib2_util.F90:147: error: argument 'fpvsnew' of command @param is not found in the argument list of grib2_util::fpvsnew(real, intent(in) t) (warning treated as error, aborting now)

fpvsnew is a function to calculate saturation water vapor pressure. And I have:

!> Compute saturation vapor pressure !! !! @param[out] fpvsnew saturation vapor pressure in Pascals !! @param[in] t temperature in Kelvin !! @author N Phillips

When removing !! @param[out] fpvsnew, I got the following Doxygen error:

/home/runner/work/UFS_UTILS/UFS_UTILS/ufs_utils/sorc/chgres_cube.fd/grib2_util.F90:154: error: return type of member grib2_util::fpvsnew is not documented (warning treated as error, aborting now)

[GeorgeGayno-NOAA]

@GeorgeGayno-NOAA Not sure how to fix the Doxygen warning to pass check tests:
/home/runner/work/UFS_UTILS/UFS_UTILS/ufs_utils/sorc/chgres_cube.fd/grib2_util.F90:147: error: argument 'fpvsnew' of command @param is not found in the argument list of grib2_util::fpvsnew(real, intent(in) t) (warning treated as error, aborting now)
fpvsnew is a function to calculate saturation water vapor pressure. And I have:
!> Compute saturation vapor pressure !! !! @param[out] fpvsnew saturation vapor pressure in Pascals !! @param[in] t temperature in Kelvin !! @author N Phillips

When removing !! @param[out] fpvsnew, I got the following Doxygen error:

/home/runner/work/UFS_UTILS/UFS_UTILS/ufs_utils/sorc/chgres_cube.fd/grib2_util.F90:154: error: return type of member grib2_util::fpvsnew is not documented (warning treated as error, aborting now)

I will take a look.

[GeorgeGayno-NOAA]

@JiliDong-NOAA For functions, doxygen requires a "@return" entry. Here is what I did to fix it:

--- a/sorc/chgres_cube.fd/grib2_util.F90
+++ b/sorc/chgres_cube.fd/grib2_util.F90
@@ -146,6 +146,7 @@ end subroutine RH2SPFH_GFS
 !> Compute saturation vapor pressure
 !!
 !! @param[in] t temperature in Kelvin
+!! @return fpvsnew Saturation vapor pressure
 !! @author N Phillips

[JiliDong-NOAA]

@JiliDong-NOAA For functions, doxygen requires a "@return" entry. Here is what I did to fix it:

--- a/sorc/chgres_cube.fd/grib2_util.F90
+++ b/sorc/chgres_cube.fd/grib2_util.F90
@@ -146,6 +146,7 @@ end subroutine RH2SPFH_GFS
 !> Compute saturation vapor pressure
 !!
 !! @param[in] t temperature in Kelvin
+!! @return fpvsnew Saturation vapor pressure
 !! @author N Phillips

Thanks @GeorgeGayno-NOAA . Now the check tests all passed. BTW, is there a way to do the compiling with debug options including Doxygen on Linux? Having to debug it online is sort of frustrating.

[GeorgeGayno-NOAA]

@JiliDong-NOAA For functions, doxygen requires a "@return" entry. Here is what I did to fix it:

--- a/sorc/chgres_cube.fd/grib2_util.F90
+++ b/sorc/chgres_cube.fd/grib2_util.F90
@@ -146,6 +146,7 @@ end subroutine RH2SPFH_GFS
 !> Compute saturation vapor pressure
 !!
 !! @param[in] t temperature in Kelvin
+!! @return fpvsnew Saturation vapor pressure
 !! @author N Phillips

Thanks @GeorgeGayno-NOAA . Now the check tests all passed. BTW, is there a way to do the compiling with debug options including Doxygen on Linux? Having to debug it online is sort of frustrating.

In the 'build_all.sh' script, turn on the following CMAKE_FLAG: -DENABLE_DOCS=ON

[JiliDong-NOAA]

@GeorgeGayno-NOAA @LarissaReames-NOAA @JeffBeck-NOAA could you review this PR? Thanks

[GeorgeGayno-NOAA]

@JiliDong-NOAA We are now committed to doing unit tests. So your new functions will need some tests.

[JiliDong-NOAA]

@JiliDong-NOAA We are now committed to doing unit tests. So your new functions will need some tests.

@GeorgeGayno-NOAA Unit test (ftst_rh2spfh_gfs) added and passed for new rh to spfh subroutines.

[JeffBeck-NOAA]

@JiliDong-NOAA, based on your issue for this PR, I assume FV3 can initialize off of RH or SPFH? Also, can you comment on how the new RH-to-SPFH calculation differs from what's already in chgres_cube, and whether that would be best for all external model data? Thanks!

[JiliDong-NOAA]

@JiliDong-NOAA, based on your issue for this PR, I assume FV3 can initialize off of RH or SPFH? Also, can you comment on how the new RH-to-SPFH calculation differs from what's already in chgres_cube, and whether that would be best for all external model data? Thanks!

@JeffBeck-NOAA I will upload several slides to show the difference.

[JiliDong-NOAA]

@JiliDong-NOAA, based on your issue for this PR, I assume FV3 can initialize off of RH or SPFH? Also, can you comment on how the new RH-to-SPFH calculation differs from what's already in chgres_cube, and whether that would be best for all external model data? Thanks!

@JeffBeck-NOAA I will upload several slides to show the difference.

@JeffBeck-NOAA Here are the comparison of different rh to spfh conversions, verified against original spfh as truth by calculating rms difference between them for three sets of grib2 files (GFSv15, v16 and grib2 from rt). Also compared with interpolating 41 levels spfh to 57 levels for one set grib2 file. Using the newly added rh2spfh conversion shows the smallest rms differences.

The new conversion is directly extracted from UPP/EMC_post and consistent with operational GFSv15/16.

Some recommendations are listed in the last slide.

qv_for GFS_grib2.pdf

[JeffBeck-NOAA]

@JiliDong-NOAA, based on your issue for this PR, I assume FV3 can initialize off of RH or SPFH? Also, can you comment on how the new RH-to-SPFH calculation differs from what's already in chgres_cube, and whether that would be best for all external model data? Thanks!

@JeffBeck-NOAA I will upload several slides to show the difference.

@JeffBeck-NOAA Here are the comparison of different rh to spfh conversions, verified against original spfh as truth by calculating rms difference between them for three sets of grib2 files (GFSv15, v16 and grib2 from rt). Also compared with interpolating 41 levels spfh to 57 levels for one set grib2 file. Using the newly added rh2spfh conversion shows the smallest rms differences.

The new conversion is directly extracted from UPP/EMC_post and consistent with operational GFSv15/16.

Some recommendations are listed in the last slide.

qv_for GFS_grib2.pdf

Thanks, @JiliDong-NOAA. It certainly looks like the new formulation of SPFH is much better!

[JiliDong-NOAA]

@GeorgeGayno-NOAA could you update the new chgres rt baseline related to GFS grib2? I have the new runs on Hera:

/scratch2/NCEPDEV/stmp1/Jili.Dong/reg-tests/chgres-cube/
c192_gfs_grib2 (Test 8)
25km_conus_gfs_grib2 (Test 9)
13km_na_gfs_ncei_grib2 (Test 14)
25km_conus_gfs_pbgrib2 (Test 16)

Thanks.

[JiliDong-NOAA]

@GeorgeGayno-NOAA Please let me know if there is any change you would like me to make.

[GeorgeGayno-NOAA]

@JiliDong-NOAA Is rh2spfh_nam used? I don't see it referenced anywhere.

[JiliDong-NOAA]

@JiliDong-NOAA Is rh2spfh_nam used? I don't see it referenced anywhere.

No, rh2spfh_nam is not used for now. It is for the future GFSv17.

[JeffBeck-NOAA]

@JiliDong-NOAA Is rh2spfh_nam used? I don't see it referenced anywhere.

No, rh2spfh_nam is not used for now. It is for the future GFSv17.

@JiliDong-NOAA, why use another formulation for GFSv17? Is there another way to calculate spfh from rh that is better than what is proposed in this PR?

[JiliDong-NOAA]

@JiliDong-NOAA Is rh2spfh_nam used? I don't see it referenced anywhere.

No, rh2spfh_nam is not used for now. It is for the future GFSv17.

@JiliDong-NOAA, why use another formulation for GFSv17? Is there another way to calculate spfh from rh that is better than what is proposed in this PR?

GFSv17 will use a different spfh to rh conversion from the previous GFS versions. For chgres, I think we would like to apply a conversion consistent with the parent or original model to be ingested (either GFS or HRRR) when calculating spfh back from rh. In this context, I think a "consistent" conversion means a "better" solution here.

[GeorgeGayno-NOAA]

@JiliDong-NOAA Is rh2spfh_nam used? I don't see it referenced anywhere.

No, rh2spfh_nam is not used for now. It is for the future GFSv17.

@JiliDong-NOAA, why use another formulation for GFSv17? Is there another way to calculate spfh from rh that is better than what is proposed in this PR?

GFSv17 will use a different spfh to rh conversion from the previous GFS versions. For chgres, I think we would like to apply a conversion consistent with the parent or original model to be ingested (either GFS or HRRR) when calculating spfh back from rh. In this context, I think a "consistent" conversion means a "better" solution here.

@JiliDong-NOAA GFS v17 parallels may not start for a while. And there is no logic to detect GFS v17 data and call that function accordingly. So, until then it a 'dead' routine. If you insist on keeping it as part of chgres, I would at least rename it - something like rh2spfh_gfsv17. Since there are multiple rh to spfh routines now, I would give each one a descriptive name. And provide enough details in the prolog so users know the difference between each function.

[JiliDong-NOAA]

@JiliDong-NOAA Is rh2spfh_nam used? I don't see it referenced anywhere.

No, rh2spfh_nam is not used for now. It is for the future GFSv17.

@JiliDong-NOAA, why use another formulation for GFSv17? Is there another way to calculate spfh from rh that is better than what is proposed in this PR?

GFSv17 will use a different spfh to rh conversion from the previous GFS versions. For chgres, I think we would like to apply a conversion consistent with the parent or original model to be ingested (either GFS or HRRR) when calculating spfh back from rh. In this context, I think a "consistent" conversion means a "better" solution here.

@JiliDong-NOAA GFS v17 parallels may not start for a while. And there is no logic to detect GFS v17 data and call that function accordingly. So, until then it a 'dead' routine. If you insist on keeping it as part of chgres, I would at least rename it - something like rh2spfh_gfsv17. Since there are multiple rh to spfh routines now, I would give each one a descriptive name. And provide enough details in the prolog so users know the difference between each function.

@GeorgeGayno-NOAA Sure, I will have rh2gfs_nam removed. Good suggestion to add some comments/details on those subroutines. I am working on it.

[JiliDong-NOAA]

@JiliDong-NOAA Is rh2spfh_nam used? I don't see it referenced anywhere.

No, rh2spfh_nam is not used for now. It is for the future GFSv17.

@JiliDong-NOAA, why use another formulation for GFSv17? Is there another way to calculate spfh from rh that is better than what is proposed in this PR?

GFSv17 will use a different spfh to rh conversion from the previous GFS versions. For chgres, I think we would like to apply a conversion consistent with the parent or original model to be ingested (either GFS or HRRR) when calculating spfh back from rh. In this context, I think a "consistent" conversion means a "better" solution here.

@JiliDong-NOAA GFS v17 parallels may not start for a while. And there is no logic to detect GFS v17 data and call that function accordingly. So, until then it a 'dead' routine. If you insist on keeping it as part of chgres, I would at least rename it - something like rh2spfh_gfsv17. Since there are multiple rh to spfh routines now, I would give each one a descriptive name. And provide enough details in the prolog so users know the difference between each function.

@GeorgeGayno-NOAA Sure, I will have rh2gfs_nam removed. Good suggestion to add some comments/details on those subroutines. I am working on it.

@GeorgeGayno-NOAA rh2spfh_nam removed and documentation added for different rh2spfh conversions. Thanks.

[GeorgeGayno-NOAA]

@GeorgeGayno-NOAA could you update the new chgres rt baseline related to GFS grib2? I have the new runs on Hera:

/scratch2/NCEPDEV/stmp1/Jili.Dong/reg-tests/chgres-cube/
c192_gfs_grib2 (Test 8)
25km_conus_gfs_grib2 (Test 9)
13km_na_gfs_ncei_grib2 (Test 14)
25km_conus_gfs_pbgrib2 (Test 16)

Thanks.

Thanks. I will update the baseline directories.

[GeorgeGayno-NOAA]

I have no further comments. @JeffBeck-NOAA and @LarissaReames-NOAA are the experts with the grib2 option. I will merge after they also approve.

[JiliDong-NOAA]

@GeorgeGayno-NOAA @JeffBeck-NOAA @LarissaReames-NOAA Please let me know if there is anything I can do for this PR.

[GeorgeGayno-NOAA]

@GeorgeGayno-NOAA @JeffBeck-NOAA @LarissaReames-NOAA Please let me know if there is anything I can do for this PR.

It looks good to me. But since I am not an expert on the grib2 option, I would like either @JeffBeck-NOAA and/or @LarissaReames-NOAA to give their approval.

[GeorgeGayno-NOAA]

Thanks, @LarissaReames-NOAA

@JiliDong-NOAA I will merge.

[JiliDong-NOAA]

Thanks, @LarissaReames-NOAA

@JiliDong-NOAA I will merge.

Thanks for you all.