Langmuir turbulence parameterization improvements

[alperaltuntas]

Pull Request Summary

This PR cleans up the calculation of Stokes drift and other diagnostics variables in WW3 for Langmuir turbulence parameterization in CESM, and removes the CESMCOUPLED ifdefs.

Description

• Provide a detailed description of what this PR does.
  • Add Langmuir turbulence parameterization
• What bug does it fix, or what feature does it add?
  • Feature - allows enabling calculation of Stokes drift diagnostic quantities.
• Is a change of answers expected from this PR?
  • No. Though the mod_defs will need to be updated.

Please also include the following information:

• Add any suggestions for a reviewer
• Mention any labels that should be added:
  • enhancement, new feature
• Are answer changes expected from this PR? Please describe the changes and the reason why in addition to which of the following labels would apply:
  • Clean up the calculations of the surface Stokes drift (USSX and USSY) and surface layer averaged Stokes drift (USSHX and USSHY). The calculation of surface layer averaged Stokes drift and the tail contributions to both versions of Stokes drift are activated when LMPENABLED flag in mod_def file is set to True. Tail contribution is added in langmuir mixing computations if SDTAIL flag is set to True. HSLMODE switch determines how HSL (surface layer depth) is specified. HSLMODE=0 means testing (where HSL is set to 10m everywhere), HSLMODE=1 means HSL is received from the nuopc cap.
  • Change the input field of mixed layer depth HML to a more general surface layer depth HSL. This depth is used to calculate the surface layer averaged Stokes drift. When used in CESM, the surface layer depth is defined as 1/5 of the mixed layer depth. Now this 1/5 factor is applied to the mixed layer depth when importing the fields in the cap.
  • Clean up the diagnostic variables for Langmuir turbulence parameterization. Some variables are intermediate quantities and are not used in the parameterization. These variables are now deleted. The key variable diagnosed in WW3 is the surface layer averaged Stokes drift (USSHX and USSHY). The Langmuir enhancement factor (LAMULT) and the surface layer averaged Langmuir number (LASL) are now calculated when they are exported in the cap. LASL is needed for the Langmuir induced entrainment parameterization in CVMix but was not there in the cap code. So it is now added following the way LAMULT is defined.
  • This PR only changes the diagnostic variables in WW3 and shouldn't change the answers of WW3.

Issue(s) addressed

• Add optional high frequency tail to USSX, USSY #669
• Add new depth input field  #670
• Move calculations to cap-code that should not be output #671

Commit Message

Clean up and refine Langmuir turbulence parameterization computations.
Authors: @qingli411, @alperaltuntas

Check list

• Branch is up to date with the authoritative repository (NOAA-EMC) develop branch.
• Checked the checklist for a developer submitting to develop.
• If a version number update is required, checked the updating version number checklist.
• If a new feature was added, a regression test for testing the new feature is added.

Testing

• How were these changes tested?
  • Testing was done in both standalone mode and coupled within UFS, documentation: Fix for ww3_tp2.22 plus updates from dev/ufs-weather-model ESCOMP/WW3#19
• Are the changes covered by regression tests? (If not, why? Do new tests need to be added?)
• Have the matrix regression tests been run (if yes, please note HPC and compiler)?
• Please indicate the expected changes in the regression test output, (Note the list of known non-identical tests.)
• Please provide the summary output of matrix.comp (matrix.Diff.txt, matrixCompFull.txt and matrixCompSummary.txt):

[alperaltuntas]

NOTE: this PR is currently a draft for an initial review from @MatthewMasarik-NOAA and/or @JessicaMeixner-NOAA. I am also mentioning @mvertens and @DeniseWorthen, who may be interested in reviewing this early version.

[MatthewMasarik-NOAA]

Awesome, @alperaltuntas, it's great to see this work! I have the UFS coupled tests running with it now. I'll post an update tomorrow.

[MatthewMasarik-NOAA]

@alperaltuntas the runs I submitted yesterday had failures due to the mod_def's. This I should have known since the PR modifies w3gridmd.F90, I needed to generate new mod_def's before running. I will be out next week, but will return and resolve this the following week. I discussed this PR with @JessicaMeixner-NOAA yesterday, and we will leave this in the Draft state while I'm away.

[JessicaMeixner-NOAA]

@alperaltuntas --- First and foremost - THANK YOU! These updates so far look good and I'm planning on taking an even closer look when I return from a conference at the end of July.

A couple of things that would be helpful in the meantime:

• Updates to model/inp/* and model/nml/* as appropriate to document new additions
• Add regression test for new features/output parameters
• Any updates that should go into the manual (Alternatively, if you'd create an issue with an assigned person + what needs to be document that will be sufficient, we'll just want to make sure we get it before the next public release).

[MatthewMasarik-NOAA]

@alperaltuntas --- First and foremost - THANK YOU! These updates so far look good and I'm planning on taking an even closer look when I return from a conference at the end of July.

A couple of things that would be helpful in the meantime:

* Updates to model/inp/* and model/nml/* as appropriate to document new additions

* Add regression test for new features/output parameters

* Any updates that should go into the manual (Alternatively, if you'd create an issue with an assigned person + what needs to be document that will be sufficient, we'll just want to make sure we get it before the next public release).

Thank you @JessicaMeixner-NOAA for this initial look and comments. @alperaltuntas I'll start to add in the items Jessica requested, so there's nothing additional needed at this point. I'll work first to get the namelist and regression test implemented. After that maybe we can touch base and together try to tackle some supporting documentation.

[mvertens]

I've suggest a load balancing exercise and some minor changes along with questions.
Frankly - I must not have submitted the suggestion - so please ignore this.

[alperaltuntas]

I've suggest a load balancing exercise and some minor changes along with questions.

@mvertens Could you clarify? I am not sure what you mean by load balancing exercise, and which minor changes and questions you are referring to.

[DeniseWorthen]

@alperaltuntas I apologize for not responding earlier. I didn't see any issues w/ your changes in terms of the mesh cap.

At some point, if this feature is used for the unstructured mesh, I think there will need to be a few changes to allow the new fields (usshx,usshy) to be written as gridded output. But I wouldn't view that as a requirement for this PR.

@MatthewMasarik-NOAA I assume you've run (or will run) the UFS RTs with these changes prior to merge?

[MatthewMasarik-NOAA]

@MatthewMasarik-NOAA I assume you've run (or will run) the UFS RTs with these changes prior to merge?

@DeniseWorthen, yes, definitely. I'm going to make a few edits for the added regtest, which I plan to complete this week. Then @JessicaMeixner-NOAA and will review including running the UFS RTs.

[DeniseWorthen]

@MatthewMasarik-NOAA Thanks. I will be able to approve once all the UFS are shown to pass.

[MatthewMasarik-NOAA]

@alperaltuntas Glad to see the polishing updates were merged in. Jessica will start her review on Monday.

[JessicaMeixner-NOAA]

matrixCompFull.txt
matrixCompSummary.txt
matrixDiff.txt

Changes are in the mod_defs and out_grd as expected. Plan to do one last test of ensuring the new regtests reproduce itself, but this PR should be good to have a ufs-weather-model PR submitted.

[JessicaMeixner-NOAA]

Thank you @alperaltuntas and @MatthewMasarik-NOAA for getting this in shape for eventual merge back to the develop branch.

@ukmo-ccbunney @mickaelaccensi @thesser1 - These updates will eventually be coming back to develop. If there's anything you see that needs to be immediately addressed, please feel free to chime in.

[mickaelaccensi]

ww3_ounf.nml and ww3_shel.nml should also be updated to add this new output field

[MatthewMasarik-NOAA]

ww3_ounf.nml and ww3_shel.nml should also be updated to add this new output field

Hi @mickaelaccensi

@JessicaMeixner-NOAA and I discussed this previously (1034#discussion) with the outcome of deciding to limit the current PR to *.inp files, and had added issue #1111 for the expansion to *.nml. Does that seem reasonable?

[mickaelaccensi]

ok, it seems acceptable to not expand this current PR with nml if it's done in another one already scheduled

[ukmo-ccbunney]

@ukmo-ccbunney @mickaelaccensi @thesser1 - These updates will eventually be coming back to develop. If there's anything you see that needs to be immediately addressed, please feel free to chime in.
Nothing is jumping out at me, so all good as far as I am concerned. 👍

[MatthewMasarik-NOAA]

Thanks for your confirmations @mickaelaccensi @ukmo-ccbunney

[MatthewMasarik-NOAA]

@alperaltuntas @JessicaMeixner-NOAA
I made small updates to the header, the main update checking off the list checkboxes.

[zach1221]

Ok, testing is complete on WM #2195. @JessicaMeixner-NOAA can you please merge this PR for us?

[MatthewMasarik-NOAA]

A belated thank you and congratulations to @qingli411 and @alperaltuntas for this very nice contribution to WW3, which was merged into the dev/ufs-weather-model branch last Friday! I'd also like to acknowledge @CarstenHansen, whose early posts to #669 provided helpful insight for implementing the namelist functionality.