Implement diagnostics for global energy fixer, check_energy standard …

…name update (#169)

Originator(s): @jimmielin

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

* Fixes #161: Add check_energy related history output variables to check_energy_diagnostics
* Fixes #166: Need to remove old CAM suite definition files
* Fixes #176 (updates `teout` standard name to
`vertically_integrated_total_energy_using_dycore_energy_formula_at_end_of_physics_timestep`)

Companion PR in SIMA: ESCOMP/CAM-SIMA#339

Describe any changes made to the namelist: N/A

List all files eliminated and why:
```
Fix #166 to remove old SDF files from scoping exercise
D       suites/suite_cam4.xml
D       suites/suite_cam6.xml
D       suites/suite_cam6_silhs.xml
```

List all files added and what they do:
```
Add global energy fixer diagnostics (teinp, teout, tefix, efix) 
A       schemes/sima_diagnostics/check_energy_fix_diagnostics.F90
A       schemes/sima_diagnostics/check_energy_fix_diagnostics.meta
```


List all existing files that have been modified, and describe the
changes:
(Helpful git command: `git diff --name-status
development...<your_branch_name>`)
```
Move some developments to check_energy_fix_diagnostics so they can be called at right time.
M       schemes/sima_diagnostics/check_energy_diagnostics.F90
M       schemes/sima_diagnostics/check_energy_diagnostics.meta

Add call to check_energy_fix_diagnostics in schemes using global energy fixer:
M       suites/suite_adiabatic.xml
M       suites/suite_cam7.xml

Update teout standard name
M       doc/NamesNotInDictionary.txt
M       schemes/check_energy/check_energy_chng.meta
M       schemes/check_energy/check_energy_gmean/check_energy_gmean.meta
M       schemes/check_energy/check_energy_save_teout.meta
M       schemes/sima_diagnostics/check_energy_diagnostics.F90
M       schemes/sima_diagnostics/check_energy_diagnostics.meta
M       schemes/sima_diagnostics/check_energy_gmean_diagnostics.meta
```

List any test failures: N/A

Is this a science-changing update? New physics package, algorithm
change, tuning changes, etc? N/A (diagnostics change only)

schemes/check_energy/check_energy_chng.meta

@@ -168,7 +168,7 @@
   dimensions = ()
   intent = out
 [ teout ]
-  standard_name = vertically_integrated_total_energy_at_end_of_physics_timestep
+  standard_name = vertically_integrated_total_energy_using_dycore_energy_formula_at_end_of_physics_timestep
   units = J m-2
   type = real | kind = kind_phys
   dimensions = (horizontal_dimension)

schemes/check_energy/check_energy_gmean/check_energy_gmean.meta

@@ -43,7 +43,7 @@
   dimensions = (horizontal_loop_extent)
   intent = in
 [ teout ]
-  standard_name = vertically_integrated_total_energy_at_end_of_physics_timestep
+  standard_name = vertically_integrated_total_energy_using_dycore_energy_formula_at_end_of_physics_timestep
   units = J m-2
   type = real | kind = kind_phys
   dimensions = (horizontal_loop_extent)
@@ -67,7 +67,7 @@
   dimensions = ()
   intent = out
 [ teout_glob ]
-  standard_name = global_mean_vertically_integrated_total_energy_at_end_of_physics_timestep
+  standard_name = global_mean_vertically_integrated_total_energy_using_dycore_energy_formula_at_end_of_physics_timestep
   units = J m-2
   type = real | kind = kind_phys
   dimensions = ()

schemes/check_energy/check_energy_save_teout.meta

@@ -18,7 +18,7 @@
   dimensions = (horizontal_loop_extent)
   intent = in
 [ teout ]
-  standard_name = vertically_integrated_total_energy_at_end_of_physics_timestep
+  standard_name = vertically_integrated_total_energy_using_dycore_energy_formula_at_end_of_physics_timestep
   units = J m-2
   type = real | kind = kind_phys
   dimensions = (horizontal_loop_extent)

schemes/sima_diagnostics/check_energy_diagnostics.F90

@@ -31,22 +31,19 @@ subroutine check_energy_diagnostics_init(errmsg, errflg)
       call history_add_field('scaling_dycore', 'ratio_of_specific_heat_of_air_used_in_physics_energy_formula_to_specific_heat_of_air_used_in_dycore_energy_formula', 'lev', 'inst', '1')
 
       call history_add_field('te_cur_phys', 'vertically_integrated_total_energy_using_physics_energy_formula', horiz_only, 'inst', 'J m-2')
-      call history_add_field('te_cur_dyn', 'vertically_integrated_total_energy_using_dycore_energy_formula', horiz_only, 'inst', 'J m-2')
       call history_add_field('tw_cur', 'vertically_integrated_total_water', horiz_only, 'inst', 'kg m-2')
 
       call history_add_field('tend_te_tnd', 'cumulative_total_energy_boundary_flux_using_physics_energy_formula', horiz_only, 'inst', 'J m-2 s-1')
       call history_add_field('tend_tw_tnd', 'cumulative_total_water_boundary_flux', horiz_only, 'inst', 'kg m-2 s-1')
 
-      call history_add_field('teout', 'vertically_integrated_total_energy_at_end_of_physics_timestep', horiz_only, 'inst', 'J m-2')
-
    end subroutine check_energy_diagnostics_init
 
    !> \section arg_table_check_energy_diagnostics_run  Argument Table
    !! \htmlinclude check_energy_diagnostics_run.html
    subroutine check_energy_diagnostics_run( &
       cp_or_cv_dycore, scaling_dycore, &
-      te_cur_phys, te_cur_dyn, tw_cur, &
-      tend_te_tnd, tend_tw_tnd, teout, &
+      te_cur_phys, tw_cur, &
+      tend_te_tnd, tend_tw_tnd, &
       errmsg, errflg)
 
       use cam_history, only: history_out_field
@@ -57,11 +54,9 @@ subroutine check_energy_diagnostics_run( &
       real(kind_phys), intent(in) :: cp_or_cv_dycore(:,:)
       real(kind_phys), intent(in) :: scaling_dycore(:,:)
       real(kind_phys), intent(in) :: te_cur_phys(:)
-      real(kind_phys), intent(in) :: te_cur_dyn(:)
       real(kind_phys), intent(in) :: tw_cur(:)
       real(kind_phys), intent(in) :: tend_te_tnd(:)
       real(kind_phys), intent(in) :: tend_tw_tnd(:)
-      real(kind_phys), intent(in) :: teout(:)
 
 
       ! CCPP error handling variables
@@ -75,11 +70,9 @@ subroutine check_energy_diagnostics_run( &
       call history_out_field('cp_or_cv_dycore', cp_or_cv_dycore)
       call history_out_field('scaling_dycore', scaling_dycore)
       call history_out_field('te_cur_phys', te_cur_phys)
-      call history_out_field('te_cur_dyn', te_cur_dyn)
       call history_out_field('tw_cur', tw_cur)
       call history_out_field('tend_te_tnd', tend_te_tnd)
       call history_out_field('tend_tw_tnd', tend_tw_tnd)
-      call history_out_field('teout', teout)
 
    end subroutine check_energy_diagnostics_run
 

schemes/sima_diagnostics/check_energy_diagnostics.meta

@@ -39,12 +39,6 @@
   type = real | kind = kind_phys
   dimensions = (horizontal_loop_extent)
   intent = in
-[ te_cur_dyn ]
-  standard_name = vertically_integrated_total_energy_using_dycore_energy_formula
-  units = J m-2
-  type = real | kind = kind_phys
-  dimensions = (horizontal_loop_extent)
-  intent = in
 [ tw_cur ]
   standard_name = vertically_integrated_total_water
   units = kg m-2
@@ -63,12 +57,6 @@
   type = real | kind = kind_phys
   dimensions = (horizontal_loop_extent)
   intent = in
-[ teout ]
-  standard_name = vertically_integrated_total_energy_at_end_of_physics_timestep
-  units = J m-2
-  type = real | kind = kind_phys
-  dimensions = (horizontal_loop_extent)
-  intent = in
 [ errmsg ]
   standard_name = ccpp_error_message
   units = none

schemes/sima_diagnostics/check_energy_fix_diagnostics.F90

@@ -0,0 +1,73 @@
+! Diagnostic scheme for check_energy_fix
+! This module includes diagnostics that have to be output
+! right after the energy fixer has been ran and check_energy_chng has updated energy state
+! (before the fluxes for check_energy_chng are zeroed out)
+module check_energy_fix_diagnostics
+   use ccpp_kinds, only: kind_phys
+
+   implicit none
+   private
+   save
+
+   public :: check_energy_fix_diagnostics_init
+   public :: check_energy_fix_diagnostics_run
+
+contains
+
+   !> \section arg_table_check_energy_fix_diagnostics_init  Argument Table
+   !! \htmlinclude check_energy_fix_diagnostics_init.html
+   subroutine check_energy_fix_diagnostics_init(errmsg, errflg)
+      use cam_history,         only: history_add_field
+      use cam_history_support, only: horiz_only
+
+      character(len=512), intent(out) :: errmsg
+      integer,            intent(out) :: errflg
+
+      ! Local variables:
+
+      errmsg = ''
+      errflg = 0
+
+      ! History add field calls
+      call history_add_field('TEINP', 'vertically_integrated_total_energy_using_dycore_energy_formula_at_start_of_physics_timestep', horiz_only, 'inst', 'J m-2')
+      call history_add_field('TEFIX', 'vertically_integrated_total_energy_using_dycore_energy_formula', horiz_only, 'inst', 'J m-2')
+      call history_add_field('TEOUT', 'vertically_integrated_total_energy_using_dycore_energy_formula_at_end_of_physics_timestep', horiz_only, 'inst', 'J m-2')
+      call history_add_field('EFIX', 'net_sensible_heat_flux_through_top_and_bottom_of_atmosphere_column_from_global_total_energy_correction', horiz_only, 'inst', 'J m-2')
+
+   end subroutine check_energy_fix_diagnostics_init
+
+   !> \section arg_table_check_energy_fix_diagnostics_run  Argument Table
+   !! \htmlinclude check_energy_diagnostics_run.html
+   subroutine check_energy_fix_diagnostics_run( &
+      te_ini_dyn, te_cur_dyn, &
+      teout, &
+      eshflx, &
+      errmsg, errflg)
+
+      use cam_history, only: history_out_field
+      !------------------------------------------------
+      !   Input / output parameters
+      !------------------------------------------------
+      ! State variables
+      real(kind_phys), intent(in) :: te_ini_dyn(:)
+      real(kind_phys), intent(in) :: te_cur_dyn(:)
+      real(kind_phys), intent(in) :: teout(:)
+      real(kind_phys), intent(in) :: eshflx(:)
+
+
+      ! CCPP error handling variables
+      character(len=512), intent(out) :: errmsg
+      integer,            intent(out) :: errflg
+
+      errmsg = ''
+      errflg = 0
+
+      ! History out field calls
+      call history_out_field('TEINP', te_ini_dyn)
+      call history_out_field('TEOUT', teout)
+      call history_out_field('TEFIX', te_cur_dyn)
+      call history_out_field('EFIX',  eshflx)
+
+   end subroutine check_energy_fix_diagnostics_run
+
+end module check_energy_fix_diagnostics

schemes/sima_diagnostics/check_energy_fix_diagnostics.meta

@@ -0,0 +1,59 @@
+[ccpp-table-properties]
+  name = check_energy_fix_diagnostics
+  type = scheme
+
+[ccpp-arg-table]
+  name  = check_energy_fix_diagnostics_init
+  type  = scheme
+[ errmsg ]
+  standard_name = ccpp_error_message
+  units = none
+  type = character | kind = len=512
+  dimensions = ()
+  intent = out
+[ errflg ]
+  standard_name = ccpp_error_code
+  units = 1
+  type = integer
+  dimensions = ()
+  intent = out
+
+[ccpp-arg-table]
+  name  = check_energy_fix_diagnostics_run
+  type  = scheme
+[ te_ini_dyn ]
+  standard_name = vertically_integrated_total_energy_using_dycore_energy_formula_at_start_of_physics_timestep
+  units = J m-2
+  type = real | kind = kind_phys
+  dimensions = (horizontal_dimension)
+  intent = in
+[ te_cur_dyn ]
+  standard_name = vertically_integrated_total_energy_using_dycore_energy_formula
+  units = J m-2
+  type = real | kind = kind_phys
+  dimensions = (horizontal_loop_extent)
+  intent = in
+[ teout ]
+  standard_name = vertically_integrated_total_energy_using_dycore_energy_formula_at_end_of_physics_timestep
+  units = J m-2
+  type = real | kind = kind_phys
+  dimensions = (horizontal_loop_extent)
+  intent = in
+[ eshflx ]
+  standard_name = net_sensible_heat_flux_through_top_and_bottom_of_atmosphere_column
+  units = W m-2
+  type = real | kind = kind_phys
+  dimensions = (horizontal_loop_extent)
+  intent = in
+[ errmsg ]
+  standard_name = ccpp_error_message
+  units = none
+  type = character | kind = len=512
+  dimensions = ()
+  intent = out
+[ errflg ]
+  standard_name = ccpp_error_code
+  units = 1
+  type = integer
+  dimensions = ()
+  intent = out

schemes/sima_diagnostics/check_energy_gmean_diagnostics.meta

@@ -34,7 +34,7 @@
   dimensions = ()
   intent = in
 [ teout_glob ]
-  standard_name = global_mean_vertically_integrated_total_energy_at_end_of_physics_timestep
+  standard_name = global_mean_vertically_integrated_total_energy_using_dycore_energy_formula_at_end_of_physics_timestep
   units = J m-2
   type = real | kind = kind_phys
   dimensions = ()

suites/suite_adiabatic.xml

@@ -7,15 +7,19 @@
     <!-- After gmean, output global mean energy diagnostics -->
     <scheme>check_energy_gmean_diagnostics</scheme>
 
-    <!-- Add global mean energy difference as heating (diff between gmean and save_teout) -->
+    <!--
+      Global energy fixer (check_energy_fix)
+      Add global mean energy difference as heating (diff between gmean and save_teout)
+    -->
     <scheme>check_energy_zero_fluxes</scheme>
     <scheme>check_energy_fix</scheme>
     <scheme>apply_heating_rate</scheme>
     <scheme>geopotential_temp</scheme>
-
-    <!-- Check that energy and water change matches the boundary fluxes -->
+    <!-- Check that energy and water change matches the boundary fluxes, update global energy -->
     <scheme>check_energy_scaling</scheme>
     <scheme>check_energy_chng</scheme>
+    <!-- Global energy fixer diagnostics (must run after check_energy_chng which updates global energies, but before zero_fluxes zeroes out boundary fluxes from energy fixer) -->
+    <scheme>check_energy_fix_diagnostics</scheme>
 
     <!-- Save current total energy from dycore for energy fixer in time step. This requires te_cur to be updated from check_energy_chng first. -->
     <scheme>check_energy_save_teout</scheme>