GFDL_atmos_cubed_sphere repo: need doc update and tag

[ligiabernardet]

A release tag, called ufs-v1.1.0, needs to be created in repository https://github.com/NOAA-GFDL/GFDL_atmos_cubed_sphere, branch release/public-v1. Before making this tag, make sure that the documentation is in order and ready to be uploaded to https://noaa-emc.github.io/FV3_Dycore_ufs-v1.1.0/html/index.html. I suggest we only make minor updates to have the version number show up properly in the HTML display.
@arunchawla-NOAA Do you have someone at EMC that can do this?

[ligiabernardet]

Today there was a meeting with @bensonr, @arunchawla-NOAA , Lauren Chilutti and myself. We decided that the we will do some documentation updates by submitting PRs to https://github.com/NOAA-GFDL/GFDL_atmos_cubed_sphere, branch release/public-v1. Once updates are ready and a tag is created, EMC will upload the HTML to https://noaa-emc.github.io/FV3_Dycore_ufs-v1.1.0/html/index.html. The list of updates is:

• EMC to do: Variables fdiag, fhout, fhmaxhf, fhouthf, and fhmax in namelist atmos_model_nml in file input.nml need to be documented
• DTC to do: Check if variable gfs_phil in namelist fv_core_nml is still used. If so, work with GFDL to document.
• GFDL to do:
  -- Variable d2bg in namelist fv_core_nml needs to be documented
  -- Variable gfs_dwinds in namelist external_ic_namelist needs to be documented
  -- Variable grid_file in namelist fv_grid_nml needs to be documented
  -- Explanation of variable d2_bg_k2 in namelist fv3_core_nml needs to be augmented to explain that when d2_bg_k2=0 the code switches to using extra diffusion.
  -- Fix typo in variable warm_start

[laurenchilutti]

Can you confirm that the Parameters List is the specific documentation you are requesting to be updated?

• the html Parameters List: https://noaa-emc.github.io/FV3_Dycore_ufs-v1.0.0/html/group__Parameters__List.html

• the FV3 doxygen code producing the html: https://github.com/NOAA-GFDL/GFDL_atmos_cubed_sphere/blob/ufs-release/public-v1/model/fv_control.F90#L650

And I have a few clarifying questions:

1. d2gb is not a variable in the code. Perhaps you meant d2_bg? d2_bg is already documented in the doxygen-based parameters listing (see line 893 in fv_control.F90). Or would you like it documented elsewhere?

2. grid_file is documented in the doxygen-based parameters listing in fv_control.F90 (see line 969). Is there another place you'd like it documented?

3. gfs_dwinds is a namelist variable in external_ic_nml that is not used and should be deleted from the code. Is that what you'd prefer?

[ligiabernardet]

Yes, I confirm that we want to update the HTML Parameter list. I believe you are correct that it originates from https://github.com/NOAA-GFDL/GFDL_atmos_cubed_sphere/blob/ufs-release/public-v1/model/fv_control.F90#L650. It would be good for you to run Doxygen and confirm. We also need an update of the version number that appears on the GitHub.io page. The current page (https://noaa-emc.github.io/FV3_Dycore_ufs-v1.0.0/html/group__Parameters__List.html) shows 1.0.0, and we need it to become 1.1.0.

• I checked d2gn and I cannot find it either. So, let's disregard this one.
• I agree that grid_file is already documented. So, let's disregard this one.
• For this release, we are not taking any more code changes. So please do not remove gfs_dwinds from the code base in the release branch. You could document it as "obsolete - to be removed" or something like that.

[ligiabernardet]

@laurenchilutti Variable gfs_phil in namelist fv_core_nml is not used in the public release or top of develop branch. Therefore you could document it by saying something like "Obsolete - will be deleted".

[laurenchilutti]

@ligiabernardet I have reached out to the FV3 team at GFDL for clarification on variable d2_bg_k2. According to them,: d2_bg_k2 is a damping parameter controlling second order diffusion for only the second model layer from the top (k=2). The only difference when d2_bg_k2 is set to 0 is that the second-order diffusion is applied to only the top-most layer (k=1) rather than to both the first and second layer (k=2). There is no new diffusion that is enabled.

With this information, I do not see a need to alter the documentation as the description for d2_bg_k2 is accurate.

[ligiabernardet]

@laurenchilutti I believe the description of d2_bg_k* you obtained from the FV3 team at GFDL is accurate for the code in the GFDL master. However, if you compare file dyn_core.F90 between the GFDL master and the public release (https://github.com/NOAA-GFDL/GFDL_atmos_cubed_sphere/blob/ufs-release/public-v1/model/dyn_core.F90), and search for d2_bg_d, you will see some differences. I believe there is something special that happens when d2_bg_k2<=0 - a sponge layer is used. I believe this was introduced by Jeff Whitaker (PSL) to help with DA for the GFS. This presentation by Catherine Thomas of EMC mentions it.

! enhanced del-2 divergence damping has same vertical structure as Rayleigh
! damping if d2_bg_k2<=0.
          if (flagstruct%d2_bg_k2 > 0) then ! old version, only applied at top two or three levels

SAME CODE AS IN GFDL MASTER

       
          else ! new version, uses d2_bg_k1 and sponge layer vertical structure
              if ( pfull(k) < flagstruct%rf_cutoff ) then
                   nord_k=0; nord_w=0
                   d2_divg = max(flagstruct%d2_bg, flagstruct%d2_bg_k1*   &
                             sin(0.5*pi*log(flagstruct%rf_cutoff/pfull(k))/log(flagstruct%rf_cutoff/ptop))**2)
                   if (first_call .and. is_master() .and. last_step) write(6,*) k, 0.01*pfull(k), d2_divg
                   damp_w = d2_divg
                   if ( flagstruct%do_vort_damp ) then
! damping on delp and vorticity
                      nord_v(k)=0
                      damp_vt(k) = 0.5*d2_divg
                   endif
              endif
          endif

[bensonr]

@ligiabernardet @laurenchilutti - Since Jeff Whitaker (PSL) made the change, then, as per community rules, he should be the one updating the documentation.

[ligiabernardet]

I have emailed Jeff to ask if he can contribute.

[laurenchilutti]

Jeff has contributed to a new description for d2_bg_k2, and per email thread with @ligiabernardet I will be removing sections A.2 (coupler_nml), A.8 (nggps_diags_nml), and A.9 (atmos_model_nml) from the dycore documentation as they are not used in the dycore.

[climbfuji]

Sounds like great progress, thanks. Once we have that documentation in, we can tag GFDL_atmos_cubed_sphere and fv3atm and move on to finalizing ufs-weather-model.

[laurenchilutti]

GFDL_atmos_cubed_sphere branch ufs-release/public-v1 now contains the documentation updates.

[climbfuji]

GFDL_atmos_cubed_sphere branch ufs-release/public-v1 now contains the documentation updates.

Thanks! I will check out this version and if all works as expected update the submodule pointer in fv3atm.

[bensonr]

@laurenchilutti @climbfuji @ligiabernardet - the documentation merge is complete in NOAA-GFDL::ufs-release/public-v1. Please double-check and create an issue in GFDL_atmos_cubed_sphere with the desired tag name.

[climbfuji]

@ligiabernardet do you want to take a look before I pull this into the release/public-v1 branch of fv3atm?

[ligiabernardet]

I took a look and it all seems reasonable to me. Thank you @laurenchilutti and @bensonr . The final test will be looking at the HTML from Doxygen to make sure sure all is in order.
@MinsukJi-NOAA, @arunchawla-NOAA said you would be the person uploading it to https://noaa-emc.github.io/FV3_Dycore_ufs-v1.1.0/html/index.html. Can you upload so we can look at it before pulling the code into the release/public-v1 branch of fv3atm?

[MinsukJi-NOAA]

I took a look and it all seems reasonable to me. Thank you @laurenchilutti and @bensonr . The final test will be looking at the HTML from Doxygen to make sure sure all is in order.
@MinsukJi-NOAA, @arunchawla-NOAA said you would be the person uploading it to https://noaa-emc.github.io/FV3_Dycore_ufs-v1.1.0/html/index.html. Can you upload so we can look at it before pulling the code into the release/public-v1 branch of fv3atm?

Will do.

[MinsukJi-NOAA]

Please take a look here

[ligiabernardet]

@laurenchilutti @MinsukJi-NOAA There is a subsection title missing in front of A.8 in https://noaa-emc.github.io/FV3_Dycore_ufs-v1.1.0/html/group__Parameters__List.html. Also, the display is missing the UFS logo in the upper left. It says the word "logo". For reference on the logo, see the v1.0.0 doc at https://noaa-emc.github.io/FV3_Dycore_ufs-v1.0.0/html/index.html.

[MinsukJi-NOAA]

image folder seems to be missing. Do you just run doxygen or is there a makefile?

[laurenchilutti]

@ligiabernardet section A.8 in v1.1 is the old section A.11 in v1.0 due to removing the 3 sections. And A.11 never had a subsection title.

[MinsukJi-NOAA]

UFS logo issue has been fixed.

[ligiabernardet]

@MinsukJi-NOAA Thanks for fixing the logo.
@laurenchilutti Do you want to add a title to A.8? Or you want this section title-less? Up to you.

[laurenchilutti]

@ligiabernardet I am discussing section A.8 this morning with Rusty. I will get back to you shortly.

[laurenchilutti]

@MinsukJi-NOAA @ligiabernardet i have addressed the lack of a title for section A.8. I have moved these variables to section A.1 as they are fv_core_nml variables. See the ufs-release/public/v1 branch at https://github.com/NOAA-GFDL/GFDL_atmos_cubed_sphere/tree/ufs-release/public-v1

[MinsukJi-NOAA]

@laurenchilutti @ligiabernardet, please check the updated documentation here.

[ligiabernardet]

Looks good to me.
@climbfuji Pls proceed to create the issue in the repo with the requested tag name.

[climbfuji]

I created PRs to update the submodule pointers and ran the regression tests, just in case. All passed.

[climbfuji]

Here is the issue: NOAA-GFDL/GFDL_atmos_cubed_sphere#52

[climbfuji]

Documentation updates were merged and tag was created: NOAA-GFDL/GFDL_atmos_cubed_sphere#52