Complete CCPPization of CAM5 UW PBL scheme (diag_TKE) by jimmielin · Pull Request #370 · ESCOMP/atmospheric_physics

jimmielin · 2026-03-09T16:10:12Z

Tag name (The PR title should also include the tag name):
Originator(s): @jimmielin

Description (include issue title and the keyword ['closes', 'fixes', 'resolves'] and issue number):

Fix qmin for chemistry/aerosol species read in from snapshot are incorrectly initialized in initialize_constituents #332 (incorrect qmin for initialize_constituents from snapshot)
Completes Convert UW PBL (diag_TKE) scheme #330 - CCPPizes UW PBL scheme (diag_TKE)
CCPPize UW interstitial to adjust diffusivity above PBL
Rearranging of interstitials for vertical diffusion, to accommodate for using either HB or UW PBL: new interstitial for handling Coords1D and potential temperature; new interstitial for computing kinematic water vapor flux and Obklen.
New stub to only zero out Beljaars, not TMS - used for CAM5 snapshot tests (TMS on, Beljaars off)

List all namelist files that were added or changed:

A       schemes/bretherton_park/bretherton_park_diff_namelist.xml
A       schemes/bretherton_park/eddy_diffusivity_adjustment_above_pbl_namelist.xml
  - for UW PBL

List all files eliminated and why: N/A

List all files added and what they do:

A       schemes/bretherton_park/bretherton_park_diff.F90
A       schemes/bretherton_park/bretherton_park_diff_namelist.xml
  - initial CCPPized subroutines for UW PBL

A       schemes/bretherton_park/eddy_diff.F90
  - moved from CAM (main driver module for UW PBL)

A       schemes/bretherton_park/eddy_diffusivity_adjustment_above_pbl.F90
A       schemes/bretherton_park/eddy_diffusivity_adjustment_above_pbl.meta
A       schemes/bretherton_park/eddy_diffusivity_adjustment_above_pbl_namelist.xml
  - mini-scheme used by the end of UW PBL

A       schemes/vertical_diffusion/vertical_diffusion_interstitials.F90
A       schemes/vertical_diffusion/vertical_diffusion_interstitials.meta
  - new interstitial for common vertical diffusion schemes
  - new interstitial for computing kinematic fluxes and Obukhov length

A       test/test_suites/suite_vdiff_bretherton_park.xml
  - SDF file

A       schemes/sima_diagnostics/bretherton_park_diff_diagnostics.F90
A       schemes/sima_diagnostics/bretherton_park_diff_diagnostics.meta
  - diagnostics for UW PBL

List all existing files that have been modified, and describe the changes:
(Helpful git command: git diff --name-status development...<your_branch_name>)

M       schemes/holtslag_boville/holtslag_boville_diff.F90
M       schemes/holtslag_boville/holtslag_boville_diff.meta
M       schemes/holtslag_boville/holtslag_boville_diff_interstitials.F90
M       schemes/holtslag_boville/holtslag_boville_diff_interstitials.meta
  - rearrange interstitials

M       schemes/sima_diagnostics/diffusion_solver_diagnostics.F90
  - comment update to clarify which surface stress is used here

M       schemes/vertical_diffusion/diffusion_solver.F90
M       schemes/vertical_diffusion/diffusion_solver.meta
  - init phase: changes for dropmixnuc (ndrop vertical mixing)-handled species to skip diffusion solver for tracers

M       schemes/vertical_diffusion/diffusion_stubs.F90
M       schemes/vertical_diffusion/diffusion_stubs.meta
  - new stub to only zero out Beljaars, not TMS
  - new stub for handling surface fluxes for dropmixnuc (ndrop vertical mixing)-handled species

M       suites/suite_cam4.xml
M       test/test_suites/suite_vdiff_holtslag_boville.xml
  - rearrange interstitials

M       test/test_schemes/initialize_constituents.F90
  - fix for #332 qmin incorrect for chemistry and aerosols species when initialized from snapshot

M       schemes/sima_diagnostics/diffusion_solver_diagnostics.F90
M       schemes/sima_diagnostics/diffusion_solver_diagnostics.meta
  - standard name update for clarity

List all automated tests that failed, as well as an explanation for why they weren't fixed:

Is this an answer-changing PR? If so, is it a new physics package, algorithm change, tuning change, etc?

If yes to the above question, describe how this code was validated with the new/modified features:

…itial

…and ndrop vertical mixing stub

…e standard name (need CAM update) -- refactor for CAM4/5 cross-compat

nusbaume

Thank you so much for helping bring in our first (!) CAM5 physics scheme @jimmielin! I realize I have what look like a ton of comments, but hopefully the vast majority of them are easy to resolve. Of course if you have any questions, comments, or concerns with any of my suggestions then just let me know. Thanks again!

nusbaume · 2026-04-13T15:54:22Z

+  integer,         parameter :: nturb = 5
+
+  real(kind_phys), parameter :: ml2 = 30.0_kind_phys**2 ! mixing lengths squared for computing free air diffusivity
+                                                        ! used for interfaces in [ntop_eddy+1, nbot_eddy]
+
+  logical,         parameter :: use_kvf = .false.       ! .true. (.false.) : initialize kvh/kvm = kvf (0)
+  real(kind_phys), parameter :: lambda  = 0.5_kind_phys ! Under-relaxation factor (0 < lambda =< 1)


We can deal with this in a future PR, but if if these are all tunable parameters then it seems like it would be better if they were namelist variables instead of hardcoded parameters. Maybe worth making a "future work" issue?

Good idea, I think we should also test if these can actually be tuned (particularly the logical paths I am worried that they might not actually work beyond the specified defaults) - added an issue here: #385

nusbaume · 2026-04-13T16:01:37Z

+    logical,         intent(in)  :: amIRoot
+    integer,         intent(in)  :: iulog
+    integer,         intent(in)  :: pver
+    integer,         intent(in)  :: pverp


I don't think pverp is actually used in this subroutine. Remove?

Thanks, removed!

nusbaume · 2026-04-13T16:37:26Z

+    use ccpp_constituent_prop_mod, only: ccpp_constituent_prop_ptr_t
+
+    ! dependency to get constituent index
+    use ccpp_const_utils,          only: ccpp_const_get_idx


Can we use the CCPP-framework equivalent for this?

Suggested change

use ccpp_const_utils, only: ccpp_const_get_idx

use ccpp_scheme_utils, only: ccpp_const_get_idx=>ccpp_constituent_index

This way we can eventually get rid of the helper scheme we currently have in atmospheric_physics.

Thanks for the suggestion! I think this doesn't have an equivalent stub in CAM yet - https://github.com/ESCOMP/CAM/blob/cam_development/src/utils/cam_ccpp/ccpp_scheme_utils.F90 is a no-op stub right now. I am happy to write the stub but that adds yet another tangential fix to the stub which will be a nightmare to my house of cards.

I added a CAM issue to write the stub: ESCOMP/CAM#1541

The atmos_phys issue is existing: #215 - I can volunteer at the end of CAM5 to sweep through all of these once the stub is in, if that is OK?

nusbaume · 2026-04-13T18:00:32Z

+    real(kind_phys), intent(inout) :: tauresx(:)          ! Residual stress to be added in vdiff to correct for turb [N m-2]
+    real(kind_phys), intent(inout) :: tauresy(:)          ! Stress mismatch between sfc and atm accumulated in prior timesteps [N m-2]


Definite nit-pick, but should we make these comments the same? I always assumed that they were the same quantity but in the X and Y directions.

No idea, I changed one but not the other. I updated it to a "two-line" comment since I need to annotate the inout, as well:

real(kind_phys), intent(inout) :: tauresx(:) ! Residual stress to be added in vdiff to correct for turb [N m-2] real(kind_phys), intent(inout) :: tauresy(:) ! (in from previous timestep; output to current timestep)

nusbaume · 2026-04-15T18:35:13Z

+    integer :: i, k, iturb
+    integer :: const_wv_idx
+    integer :: ipbl(ncol)     ! If 1, PBL is CL, while if 0, PBL is STL.
+    integer :: kpblh(ncol)    ! Layer index containing PBL top within or at the base interface (NOT USED)


If this isn't used then can we get rid of it entirely? It looks like it is purely diagnostic in caleddy (i.e. not used in any other variable calculations).

Thanks, confirmed and removed!

nusbaume · 2026-04-21T17:14:50Z

+      ! The following code is overbuilt for when ncvmax < pver
+      if (ncvmax < pver) then
+         tmp_lev = 0.0_kind_phys
+         tmp_lev(:, :ncvmax) = kbase_o(:, :ncvmax)


Is this order correct, or should it go from the bottom to the top of ncvmax?

Suggested change

tmp_lev(:, :ncvmax) = kbase_o(:, :ncvmax)

tmp_lev(:, (pver-ncvmax+1):pver) = kbase_o(:, ncvmax:)

This same question holds for all of the tmp_lev(:,:ncvmax) lines below as well.

This order is correct although strange. See eddy_diff.F90:

! The CL nearest to the surface is CL(1) and the CL index, ncv, increases ! with height. The following outputs are from 'zisocl'. Here, the dimension ! of below outputs are (ncol,ncvmax) (except the 'ncvfin(ncol)' and ! 'belongcv(ncol,pver+1)) and 'ncv' goes from 1 to 'ncvfin'.

the ordering of the ncv diagnostics confusingly have no relationship with the vertical grid of the output (they just borrow the second dimension). CAM also just outputs these directly without vertical reordering.

nusbaume · 2026-04-21T19:32:49Z

-    <!-- hb pre-interstitial: tautotx/y -->
-    <scheme>tms_beljaars_zero_stub</scheme> <!-- stub as TMS/Beljaars not implemented -->
-    <scheme>hb_diff_set_total_surface_stress</scheme>
+    <!-- stub as TMS/Beljaars not used in CAM4 -->


Given that we will now have our first CAM5 physics scheme, should we go ahead and create a suite_cam5.xml SDF as well? I believe it will basically be the same as suite_cam4.xml, except with HB replaced with Bretherthon-Park, Hack replaced with the UW shallow scheme, RK replaced with the Park macrophysics and PUMAS microphysics schemes, the cloud fraction schemes replaced with the "two moment" schemes, and the addition of the Beljaars form drag scheme.

Of course if you would like help with setting up the initial version of the SDF, or want to punt it to future work, then just let me know!

For some reason I wrote it but only for uwshcu. Added now, thanks for the reminder!

nusbaume · 2026-04-21T19:33:47Z

             errmsg = errmsg)
       else
+          ! For chemistry species some special handling is necessary for qmin_value;
+          ! this logic is replicated from chem_register in src/chemistry/mozart.


I would just emphasize that this code is from CAM:

Suggested change

! this logic is replicated from chem_register in src/chemistry/mozart.

! this logic is replicated from chem_register in src/chemistry/mozart in CAM.

Updated, also will merge this file's more advanced version earlier in #384

nusbaume · 2026-04-21T19:42:04Z

+    <!-- vdiff pre-interstitial 3: calculate total surface stresses
+         used for surface momentum flux diagnostic.
+         here, also used for HB. -->


Do we need this part of the comment given that HB isn't being used in this SDF?

Suggested change

I removed it since it was confusing, I meant this scheme was shared with HB as a reminder for when I was scoping out all of this. Thanks!

nusbaume · 2026-04-21T19:43:10Z

+
+    <!-- vdiff pre-interstitial 5: calculate damping rate from drag coef. -->
+    <scheme>vertical_diffusion_wind_damping_rate</scheme>
+    <!--<scheme>beljaars_add_wind_damping_rate</scheme>-->


Do we need this commented-out scheme in this test SDF?

Not here, but it needs to be added to the CAM5 suite when Beljaars is CCPPized. I kept it in suite_cam5 but removed it here.

Co-authored-by: Jesse Nusbaumer <nusbaume@ucar.edu>

jimmielin added 15 commits March 9, 2026 11:58

Initial push of UW PBL

86dd6e9

Update interfaces to run phase

a972d91

Refactor HB: move kinematic fluxes and obklen to common vdiff interst…

a3a6794

…itial

Draft metadata

a544023

Remove unused metadata that was removed

8e83bb0

Keep removing moved metadata

3e6fb40

Keep removing moved metadata (2)

1f935fc

Initial fixes for b4b in SIMA -- up to constituent diffusion

633b8a6

Fix for ESCOMP#332

06fdad4

Handle dropmixnuc; batch of fixes for constituent vertical diffusion …

8de2a05

…and ndrop vertical mixing stub

Change cflx from coupler to from interstitial

92c64a8

Do not mutate const_array; mutate q1 in vdiff ndropmixed alternate

0a75ad2

Sketch out UW PBL diagnostics; REARRANGE HB tautotx/tautoty and chang…

ca7f025

…e standard name (need CAM update) -- refactor for CAM4/5 cross-compat

Fix turbtype_real dimension to pverp

7896907

Remove extraneous comments (as they are documented in the actual scheme)

c47066c

jimmielin self-assigned this Mar 9, 2026

jimmielin added the enhancement New feature or request label Mar 9, 2026

jimmielin added this to CAM Development Mar 9, 2026

jimmielin mentioned this pull request Mar 9, 2026

Complete CCPPization of CAM5 UW (diag_TKE) PBL scheme; cleanup to vertical_diffusion_tend ESCOMP/CAM#1445

Open

Fix qrl unit - should be adj by pressure thickness

f7ca8e7

jimmielin requested a review from nusbaume March 11, 2026 16:36

jimmielin mentioned this pull request Mar 17, 2026

Science/Cleanup: Verify handling of surface stresses for PBL scheme vs. diffusion solver #309

Open

nusbaume requested changes Apr 21, 2026

View reviewed changes

This comment was marked as duplicate.

Sign in to view

Merge branch 'main' into hplin/diag_tke_rebase_main

ea0f256

jimmielin and others added 2 commits April 21, 2026 17:11

Address review comments.

7b38644

Update schemes/bretherton_park/bretherton_park_diff.meta

466253f

Co-authored-by: Jesse Nusbaumer <nusbaume@ucar.edu>

jimmielin requested a review from nusbaume April 21, 2026 21:12

	use ccpp_const_utils, only: ccpp_const_get_idx
	use ccpp_scheme_utils, only: ccpp_const_get_idx=>ccpp_constituent_index

		real(kind_phys), intent(inout) :: tauresx(:) ! Residual stress to be added in vdiff to correct for turb [N m-2]
		real(kind_phys), intent(inout) :: tauresy(:) ! Stress mismatch between sfc and atm accumulated in prior timesteps [N m-2]

	tmp_lev(:, :ncvmax) = kbase_o(:, :ncvmax)
	tmp_lev(:, (pver-ncvmax+1):pver) = kbase_o(:, ncvmax:)

	! this logic is replicated from chem_register in src/chemistry/mozart.
	! this logic is replicated from chem_register in src/chemistry/mozart in CAM.

Conversation

jimmielin commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nusbaume left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as duplicate.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jimmielin commented Mar 9, 2026 •

edited

Loading