Add new Tiedtke convection scheme (ESCOMP#267)

### Originator(s):

kuanchihwang

### Descriptions (include the issue title, and the keyword ['closes',
'fixes', 'resolves'] followed by the issue number):

This PR adds the new Tiedtke convection scheme to the experimental
convection-permitting physics suite.

### List all namelist files that were added or changed:

None

### List all files eliminated and why:

None

### List all files added and what they do:

```
A       schemes/mmm/cu_ntiedtke_compat.F90
A       schemes/mmm/cu_ntiedtke_compat.meta
  * Implement new Tiedtke cumulus scheme
```

### List all existing files that have been modified, and describe the
changes:

```
M       schemes/mmm/bl_gwdo_compat.F90
  * Factor out computation of characteristic grid length scale
M       schemes/mmm/bl_gwdo_compat.meta
  * Fix standard names and attributes
  * Factor out computation of characteristic grid length scale
M       schemes/mmm/mmm_physics
  * Update mmm-physics submodule
M       schemes/mmm/mmm_physics_compat.F90
  * Factor out computation of characteristic grid length scale
  * Implement conversion between geopotential height at interface wrt surface and mean sea level
  * Implement interstitial schemes for new Tiedtke cumulus scheme
M       schemes/mmm/mmm_physics_compat.meta
  * Fix standard names and attributes
  * Factor out computation of characteristic grid length scale
  * Implement conversion between geopotential height at interface wrt surface and mean sea level
  * Implement interstitial schemes for new Tiedtke cumulus scheme
M       schemes/utilities/state_converters.F90
  * Implement conversion between dry and wet cloud ice mixing ratio
M       schemes/utilities/state_converters.meta
  * Implement conversion between dry and wet cloud ice mixing ratio
M       test/test_suites/suite_convection_permitting.xml
  * Update suite definition file
M       test/unit-test/tests/mmm/mmm_physics_compat_tests.pf
  * Update unit tests
```

### List all automated tests that failed, as well as an explanation for
why they were not fixed:

None

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

Answer-changing for the convection-permitting physics suite due to a
newly added physics scheme. Nothing is changed for the rest.

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

The convection-permitting physics suite is considered an experimental
feature. There is no baseline available to validate against because it
has never been implemented in CAM-SIMA as well as CAM before.

Author: kuanchihwang-ncar

schemes/mmm/bl_gwdo_compat.F90

@@ -13,13 +13,11 @@ module bl_gwdo_compat
     !> \section arg_table_bl_gwdo_compat_pre_init Argument Table
     !! \htmlinclude bl_gwdo_compat_pre_init.html
     pure subroutine bl_gwdo_compat_pre_init( &
-            omega, rearth, &
-            dxmeter, sina, cosa, &
+            sina, cosa, &
             errmsg, errflg)
         use ccpp_kinds, only: kind_phys
 
-        real(kind_phys), intent(in) :: omega(:), rearth
-        real(kind_phys), intent(out) :: dxmeter(:), sina(:), cosa(:)
+        real(kind_phys), intent(out) :: sina(:), cosa(:)
         character(*), intent(out) :: errmsg
         integer, intent(out) :: errflg
 
@@ -28,10 +26,6 @@ pure subroutine bl_gwdo_compat_pre_init( &
 
         ! These variables do not change with time. Set them just once at model initialization for better performance.
 
-        ! The "bl_gwdo" physics scheme needs grid sizes in meters. This is trivial for models with regular grids like WRF,
-        ! but not so straightforward for models with unstructured grids like CAM-SIMA. Here, the square root of cell area is used.
-        dxmeter(:) = sqrt(omega(:) * (rearth ** 2))
-
         ! The "bl_gwdo" physics scheme was originally designed to be used with regional models like WRF, where the positive X and
         ! Y directions may not always point to the east and north, respectively. This is no longer the case for global models like
         ! CAM-SIMA.

schemes/mmm/bl_gwdo_compat.meta

@@ -5,24 +5,6 @@
 [ccpp-arg-table]
   name = bl_gwdo_compat_pre_init
   type = scheme
-[ omega ]
-  standard_name = cell_angular_area
-  units = sr
-  type = real | kind = kind_phys
-  dimensions = (horizontal_dimension)
-  intent = in
-[ rearth ]
-  standard_name = radius_of_earth
-  units = m
-  type = real | kind = kind_phys
-  dimensions = ()
-  intent = in
-[ dxmeter ]
-  standard_name = characteristic_grid_lengthscale
-  units = m
-  type = real | kind = kind_phys
-  dimensions = (horizontal_dimension)
-  intent = out
 [ sina ]
   standard_name = sine_of_angle_of_rotation_from_east_to_x
   units = 1
@@ -115,13 +97,13 @@
   dimensions = (horizontal_loop_extent)
   intent = in
 [ rublten ]
-  standard_name = tendency_of_x_wind_due_to_pbl_processes
+  standard_name = tendency_of_eastward_wind_due_to_pbl_processes
   units = m s-2
   type = real | kind = kind_phys
   dimensions = (horizontal_loop_extent, vertical_layer_dimension)
   intent = inout
 [ rvblten ]
-  standard_name = tendency_of_y_wind_due_to_pbl_processes
+  standard_name = tendency_of_northward_wind_due_to_pbl_processes
   units = m s-2
   type = real | kind = kind_phys
   dimensions = (horizontal_loop_extent, vertical_layer_dimension)
@@ -169,12 +151,11 @@
   dimensions = (horizontal_loop_extent, vertical_layer_dimension)
   intent = in
 [ q1 ]
-  standard_name = water_vapor_mixing_ratio_wrt_moist_air_and_condensed_water
+  standard_name = water_vapor_mixing_ratio_wrt_dry_air
   units = kg kg-1
   type = real | kind = kind_phys
   dimensions = (horizontal_loop_extent, vertical_layer_dimension)
   intent = in
-  advected = true
 [ prsi ]
   standard_name = air_pressure_at_interface
   units = Pa

schemes/mmm/cu_ntiedtke_compat.F90

@@ -0,0 +1,237 @@
+!> This module contains interstitial schemes that are specific to new Tiedtke cumulus scheme,
+!> which is part of MMM physics.
+module cu_ntiedtke_compat
+    implicit none
+
+    private
+    public :: cu_ntiedtke_compat_pre_run
+    public :: cu_ntiedtke_compat_init
+    public :: cu_ntiedtke_compat_run
+    public :: cu_ntiedtke_diagnostics_init
+    public :: cu_ntiedtke_diagnostics_run
+contains
+    !> \section arg_table_cu_ntiedtke_compat_pre_run Argument Table
+    !! \htmlinclude cu_ntiedtke_compat_pre_run.html
+    subroutine cu_ntiedtke_compat_pre_run( &
+            cflx, exner, landfrac, &
+            lhf, shf, &
+            rthdynten, rthblten, rthratenlw, rthratensw, &
+            rqvdynten, rqvblten, &
+            lndj, &
+            ptf, pqvf, hfx, evap, &
+            errmsg, errflg)
+        use ccpp_kinds, only: kind_phys
+        use ccpp_scheme_utils, only: ccpp_constituent_index
+
+        real(kind_phys), intent(in) :: cflx(:, :), exner(:, :), landfrac(:), &
+                                       lhf(:), shf(:), &
+                                       rthdynten(:, :), rthblten(:, :), rthratenlw(:, :), rthratensw(:, :), &
+                                       rqvdynten(:, :), rqvblten(:, :)
+        integer, intent(out) :: lndj(:)
+        real(kind_phys), intent(out) :: ptf(:, :), pqvf(:, :), hfx(:), evap(:)
+        character(*), intent(out) :: errmsg
+        integer, intent(out) :: errflg
+
+        integer :: water_vapor_mixing_ratio_index
+
+        where (landfrac >= 0.5_kind_phys)
+            lndj = 1
+        elsewhere
+            lndj = 0
+        end where
+
+        ptf(:, :) = (rthdynten(:, :) + rthblten(:, :) + rthratenlw(:, :) + rthratensw(:, :)) * exner(:, :)
+        pqvf(:, :) = rqvdynten(:, :) + rqvblten(:, :)
+        hfx(:) = lhf(:) + shf(:)
+        evap(:) = 0.0_kind_phys
+
+        call ccpp_constituent_index( &
+            'water_vapor_mixing_ratio_wrt_moist_air_and_condensed_water', water_vapor_mixing_ratio_index, errflg, errmsg)
+
+        if (errflg /= 0 .or. &
+            water_vapor_mixing_ratio_index < lbound(cflx, 2) .or. water_vapor_mixing_ratio_index > ubound(cflx, 2)) then
+            errmsg = 'Failed to find desired constituent flux from cflx'
+            errflg = 1
+
+            return
+        end if
+
+        evap(:) = cflx(:, water_vapor_mixing_ratio_index)
+
+        errmsg = ''
+        errflg = 0
+    end subroutine cu_ntiedtke_compat_pre_run
+
+    !> \section arg_table_cu_ntiedtke_compat_init Argument Table
+    !! \htmlinclude cu_ntiedtke_compat_init.html
+    subroutine cu_ntiedtke_compat_init( &
+            con_cp, con_rd, con_rv, con_xlv, con_xls, con_xlf, con_grav, &
+            errmsg, errflg)
+        use ccpp_kinds, only: kind_phys
+        use cu_ntiedtke, only: cu_ntiedtke_init
+
+        real(kind_phys), intent(in) :: con_cp, con_rd, con_rv, con_xlv, con_xls, con_xlf, con_grav
+        character(*), intent(out) :: errmsg
+        integer, intent(out) :: errflg
+
+        call cu_ntiedtke_init( &
+            con_cp, con_rd, con_rv, con_xlv, con_xls, con_xlf, con_grav, &
+            errmsg, errflg)
+
+        errmsg = ''
+        errflg = 0
+    end subroutine cu_ntiedtke_compat_init
+
+    !> \section arg_table_cu_ntiedtke_compat_run Argument Table
+    !! \htmlinclude cu_ntiedtke_compat_run.html
+    subroutine cu_ntiedtke_compat_run( &
+            pu, pv, pt, pqv, pqc, pqi, &
+            pqvf, ptf, poz, pzz, pomg, &
+            pap, paph, evap, hfx, zprecc, lndj, lq, km, km1, dt, dx, &
+            exner, &
+            rucuten, rvcuten, rthcuten, rqvcuten, rqccuten, rqicuten, &
+            errmsg, errflg)
+        use ccpp_kinds, only: kind_phys
+        use cu_ntiedtke, only: cu_ntiedtke_run
+
+        integer, intent(in) :: lndj(:), lq, km, km1
+        real(kind_phys), intent(in) :: pu(:, :), pv(:, :), pt(:, :), pqv(:, :), pqc(:, :), pqi(:, :), &
+                                       pqvf(:, :), ptf(:, :), poz(:, :), pzz(:, :), pomg(:, :), &
+                                       pap(:, :), paph(:, :), evap(:), hfx(:), &
+                                       dt, dx(:), &
+                                       exner(:, :)
+        real(kind_phys), intent(out) :: zprecc(:), &
+                                        rucuten(:, :), rvcuten(:, :), &
+                                        rthcuten(:, :), &
+                                        rqvcuten(:, :), rqccuten(:, :), rqicuten(:, :)
+        character(*), intent(out) :: errmsg
+        integer, intent(out) :: errflg
+
+        real(kind_phys), allocatable :: pu_local(:, :), pv_local(:, :), &
+                                        pt_local(:, :), &
+                                        pqv_local(:, :), pqc_local(:, :), pqi_local(:, :)
+
+        zprecc(:) = 0.0_kind_phys
+
+        rucuten(:, :) = 0.0_kind_phys
+        rvcuten(:, :) = 0.0_kind_phys
+        rthcuten(:, :) = 0.0_kind_phys
+        rqvcuten(:, :) = 0.0_kind_phys
+        rqccuten(:, :) = 0.0_kind_phys
+        rqicuten(:, :) = 0.0_kind_phys
+
+        ! The "cu_ntiedtke" physics scheme modifies model states directly, which is not ideal.
+        ! Make local copies of the model states, pass them to the physics scheme, and compute the tendencies instead.
+
+        allocate(pu_local, source=pu, errmsg=errmsg, stat=errflg)
+
+        if (errflg /= 0) then
+            return
+        end if
+
+        allocate(pv_local, source=pv, errmsg=errmsg, stat=errflg)
+
+        if (errflg /= 0) then
+            return
+        end if
+
+        allocate(pt_local, source=pt, errmsg=errmsg, stat=errflg)
+
+        if (errflg /= 0) then
+            return
+        end if
+
+        allocate(pqv_local, source=pqv, errmsg=errmsg, stat=errflg)
+
+        if (errflg /= 0) then
+            return
+        end if
+
+        allocate(pqc_local, source=pqc, errmsg=errmsg, stat=errflg)
+
+        if (errflg /= 0) then
+            return
+        end if
+
+        allocate(pqi_local, source=pqi, errmsg=errmsg, stat=errflg)
+
+        if (errflg /= 0) then
+            return
+        end if
+
+        call cu_ntiedtke_run( &
+            pu_local, pv_local, pt_local, pqv_local, pqc_local, pqi_local, &
+            pqvf, ptf, poz, pzz, pomg, &
+            pap, paph, evap, hfx, zprecc, lndj, lq, km, km1, dt, dx, &
+            errmsg, errflg)
+
+        zprecc(:) = zprecc(:) * 0.001_kind_phys ! Convert from mm to m.
+
+        rucuten(:, :) = (pu_local(:, :) - pu(:, :)) / dt
+        rvcuten(:, :) = (pv_local(:, :) - pv(:, :)) / dt
+        rthcuten(:, :) = (pt_local(:, :) - pt(:, :)) / exner(:, :) / dt
+        rqvcuten(:, :) = (pqv_local(:, :) - pqv(:, :)) / dt
+        rqccuten(:, :) = (pqc_local(:, :) - pqc(:, :)) / dt
+        rqicuten(:, :) = (pqi_local(:, :) - pqi(:, :)) / dt
+
+        errmsg = ''
+        errflg = 0
+    end subroutine cu_ntiedtke_compat_run
+
+    !> \section arg_table_cu_ntiedtke_diagnostics_init Argument Table
+    !! \htmlinclude cu_ntiedtke_diagnostics_init.html
+    subroutine cu_ntiedtke_diagnostics_init( &
+            errmsg, errflg)
+        use cam_history, only: history_add_field
+        use cam_history_support, only: horiz_only
+
+        character(*), intent(out) :: errmsg
+        integer, intent(out) :: errflg
+
+        call history_add_field('cu_ntiedtke_zprecc', &
+            'lwe_thickness_of_convective_precipitation_amount', horiz_only, 'avg', 'm')
+        call history_add_field('cu_ntiedtke_rucuten', &
+            'tendency_of_eastward_wind_due_to_convection', 'lev', 'avg', 'm s-2')
+        call history_add_field('cu_ntiedtke_rvcuten', &
+            'tendency_of_northward_wind_due_to_convection', 'lev', 'avg', 'm s-2')
+        call history_add_field('cu_ntiedtke_rthcuten', &
+            'tendency_of_air_potential_temperature_due_to_convection', 'lev', 'avg', 'K s-1')
+        call history_add_field('cu_ntiedtke_rqvcuten', &
+            'tendency_of_water_vapor_mixing_ratio_wrt_dry_air_due_to_convection', 'lev', 'avg', 'kg kg-1 s-1')
+        call history_add_field('cu_ntiedtke_rqccuten', &
+            'tendency_of_cloud_liquid_water_mixing_ratio_wrt_dry_air_due_to_convection', 'lev', 'avg', 'kg kg-1 s-1')
+        call history_add_field('cu_ntiedtke_rqicuten', &
+            'tendency_of_cloud_ice_mixing_ratio_wrt_dry_air_due_to_convection', 'lev', 'avg', 'kg kg-1 s-1')
+
+        errmsg = ''
+        errflg = 0
+    end subroutine cu_ntiedtke_diagnostics_init
+
+    !> \section arg_table_cu_ntiedtke_diagnostics_run Argument Table
+    !! \htmlinclude cu_ntiedtke_diagnostics_run.html
+    subroutine cu_ntiedtke_diagnostics_run( &
+            zprecc, &
+            rucuten, rvcuten, rthcuten, rqvcuten, rqccuten, rqicuten, &
+            errmsg, errflg)
+        use cam_history, only: history_out_field
+        use ccpp_kinds, only: kind_phys
+
+        real(kind_phys), intent(in) :: zprecc(:), &
+                                       rucuten(:, :), rvcuten(:, :), &
+                                       rthcuten(:, :), &
+                                       rqvcuten(:, :), rqccuten(:, :), rqicuten(:, :)
+        character(*), intent(out) :: errmsg
+        integer, intent(out) :: errflg
+
+        call history_out_field('cu_ntiedtke_zprecc', zprecc)
+        call history_out_field('cu_ntiedtke_rucuten', rucuten)
+        call history_out_field('cu_ntiedtke_rvcuten', rvcuten)
+        call history_out_field('cu_ntiedtke_rthcuten', rthcuten)
+        call history_out_field('cu_ntiedtke_rqvcuten', rqvcuten)
+        call history_out_field('cu_ntiedtke_rqccuten', rqccuten)
+        call history_out_field('cu_ntiedtke_rqicuten', rqicuten)
+
+        errmsg = ''
+        errflg = 0
+    end subroutine cu_ntiedtke_diagnostics_run
+end module cu_ntiedtke_compat