Export CO2 value to the land model via coupler (ESCOMP#427)

Tag name (The PR title should also include the tag name):
Originator(s): @jimmielin assisted-by claude-fable:5

Description (include issue title and the keyword ['closes', 'fixes',
'resolves'] and issue number):
- Update the `set_surface_coupling_vars` scheme to pass the
`prescribed_volume_mixing_ratio_of_co2` prescribed via
`prescribe_radiative_gas_concentrations` to the coupler

CAM just does this in `camsrfexch.F90`
```fortran
cam_out%co2diag(:ncol) = chem_surfvals_get('CO2VMR') * 1.0e+6_r8
```

List all namelist files that were added or changed: 
A       schemes/utilities/set_surface_coupling_vars_namelist.xml

List all files eliminated and why:

List all files added and what they do: N/A

List all existing files that have been modified, and describe the
changes:
(Helpful git command: `git diff --name-status
main...<your_branch_name>`)
```
M       schemes/utilities/set_surface_coupling_vars.F90
M       schemes/utilities/set_surface_coupling_vars.meta
  - update to set co2diag, co2prog
```

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:

---------

Co-authored-by: Haipeng Lin <hplin+github@ucar.edu>
Co-authored-by: Jesse Nusbaumer <nusbaume@ucar.edu>
Co-authored-by: Haipeng Lin <hplin@ucar.edu>

Author: 4 people

schemes/utilities/set_surface_coupling_vars.F90

@@ -1,7 +1,7 @@
 !-----------------------------------------------------------------------
 ! Module to handle data that is exchanged between the atmosphere
 ! model and the surface models (land, sea-ice, ocean, etc.).
-
+!
 ! Please note that currently this is a SIMA-specific module,
 ! but could be made more host model-independent in the future.
 !-----------------------------------------------------------------------
@@ -24,17 +24,20 @@ subroutine set_surface_coupling_vars_run(ncol, pver, ncnst, gravit, rair, phis,
                                          surf_pres, air_temp, inv_ps_exner, zm,     &
                                          rho, uwnd, vwnd, air_pres, cnst_array,     &
                                          prec_dp, snow_dp, prec_sh, snow_sh,        &
-                                         prec_str, snow_str, air_temp_bot,          &
+                                         prec_str, snow_str, do_diagnostic_co2,     &
+                                         air_temp_bot,                              &
                                          pot_temp_bot, zm_bot, rho_bot,             &
                                          uwnd_bot, vwnd_bot, air_pres_bot,          &
                                          topo_height, sea_lev_pres, cnst_bot,       &
                                          conv_prec, conv_snow, strat_prec,          &
-                                         strat_snow, errmsg, errcode)
+                                         strat_snow, co2diag, co2prog,              &
+                                         errmsg, errcode)
 
    ! Set surface variables needed for atmosphere-surface coupling.
 
    ! Use statements
-   use ccpp_kinds,       only: kind_phys
+   use ccpp_kinds,        only: kind_phys
+   use ccpp_scheme_utils, only: ccpp_constituent_index
 
    ! Input arguments
    integer, intent(in) :: ncol
@@ -61,6 +64,8 @@ subroutine set_surface_coupling_vars_run(ncol, pver, ncnst, gravit, rair, phis,
    real(kind_phys), intent(in) :: prec_str(:)       ! LWE stratiform precipitation (all phases) [m s-1]
    real(kind_phys), intent(in) :: snow_str(:)       ! LWE stratiform frozen precipitation (e.g. snow) [m s-1]
 
+   logical, intent(in) :: do_diagnostic_co2         ! Export CO2 in the diagnostic (T) or prognostic (F) coupler field [flag]
+
    ! Output arguments
    real(kind_phys), intent(out) :: air_temp_bot(:) ! Air temperature at bottom of atmosphere for coupling [K]
    real(kind_phys), intent(out) :: pot_temp_bot(:) ! Potential air temprature at bottom of atmosphere for coupling [K]
@@ -78,14 +83,22 @@ subroutine set_surface_coupling_vars_run(ncol, pver, ncnst, gravit, rair, phis,
    real(kind_phys), intent(out) :: strat_prec(:)   ! LWE Stratiform (large-scale) precipitation (all phases) [m s-1]
    real(kind_phys), intent(out) :: strat_snow(:)   ! LWE Frozen stratiform (large-scale)precipitation (e.g. snow) [m s-1]
 
+   real(kind_phys), intent(out) :: co2diag(:)      ! Diagnostic CO2 volume mixing ratio for coupler [ppmv]
+   real(kind_phys), intent(out) :: co2prog(:)      ! Prognostic CO2 volume mixing ratio for coupler [ppmv]
+
    character(len=512), intent(out) :: errmsg       ! CCPP error message
    integer,            intent(out) :: errcode      ! CCPP error code
 
    ! Local variables
-
    integer :: i              ! column index
    integer :: m              ! constituent index
 
+   integer         :: co2_idx   ! CO2 constituent index
+
+   ! Ratio of dry air molar mass to CO2 molar mass.
+   ! Duplicated from radiation_utils rather than used from there to avoid a build dependency.
+   real(kind_phys), parameter :: dry_air_to_co2_molar_mass_ratio = 0.658114_kind_phys
+
    !-----------------------------------------------------------------------
 
    errmsg  = ''
@@ -114,6 +127,27 @@ subroutine set_surface_coupling_vars_run(ncol, pver, ncnst, gravit, rair, phis,
      end do
    end do
 
+   ! Export the CO2 volume mixing ratio for surface models.
+   ! do_diagnostic_co2 selects whether it is sent in the diagnostic
+   ! or prognostic coupler field (for surface model).
+   co2diag(:) = 0._kind_phys
+   co2prog(:) = 0._kind_phys
+   call ccpp_constituent_index('CO2', co2_idx, errcode, errmsg)
+   if (errcode /= 0) return
+
+   if (co2_idx > 0) then
+     ! Convert bottom-layer dry mass mixing ratio to ppmv expected by the coupler:
+     if (do_diagnostic_co2) then
+       do i = 1, ncol
+         co2diag(i) = cnst_array(i,pver,co2_idx) * dry_air_to_co2_molar_mass_ratio * 1.0e+6_kind_phys
+       end do
+     else
+       do i = 1, ncol
+         co2prog(i) = cnst_array(i,pver,co2_idx) * dry_air_to_co2_molar_mass_ratio * 1.0e+6_kind_phys
+       end do
+     end if
+   end if
+
    !
    ! Precipation and snow rates from shallow convection, deep convection and stratiform processes.
    ! Compute total convective and stratiform precipitation and snow rates

schemes/utilities/set_surface_coupling_vars.meta

@@ -136,6 +136,12 @@
   type = real | kind = kind_phys
   dimensions = (horizontal_loop_extent)
   intent = in
+[ do_diagnostic_co2 ]
+  standard_name = do_diagnostic_co2_export_to_coupler
+  units = flag
+  type = logical
+  dimensions = ()
+  intent = in
 
 #----------------
 #Output Arguments
@@ -225,6 +231,18 @@
   type = real | kind = kind_phys
   dimensions = (horizontal_loop_extent)
   intent = out
+[ co2diag ]
+  standard_name = diagnostic_volume_mixing_ratio_of_co2_to_coupler
+  units = ppmv
+  type = real | kind = kind_phys
+  dimensions = (horizontal_loop_extent)
+  intent = out
+[ co2prog ]
+  standard_name = prognostic_volume_mixing_ratio_of_co2_to_coupler
+  units = ppmv
+  type = real | kind = kind_phys
+  dimensions = (horizontal_loop_extent)
+  intent = out
 [ errmsg ]
   standard_name = ccpp_error_message
   units = none

schemes/utilities/set_surface_coupling_vars_namelist.xml

@@ -0,0 +1,94 @@
+<?xml version="1.0"?>
+
+<?xml-stylesheet type="text/xsl"?>
+
+<entry_id_pg version="2.0">
+
+<!-- Each namelist variable is defined in an <entry> element.  The
+     content of the element is the documentation of how the variable is
+     used.  Other aspects of the variable's definition are expressed as
+     attributes of the <entry> element.  Note that it is an XML requirement
+     that the attribute values are enclosed in quotes.  The attributes are:
+
+     id
+          The variable's name.  *** N.B. *** The name must be lower case.
+          The module convert all namelist variable names to lower case
+          since Fortran is case insensitive.
+
+     type
+          An abbreviation of the fortran declaration for the variable.
+       Valid declarations are:
+
+          char*n
+          integer
+          logical
+          real
+
+       Any of these types may be followed by a comma separated list of
+       integers enclosed in parenthesis to indicate an array.
+
+       The current namelist validation code only distinquishes between
+       string and non-string types.
+
+     input_pathname
+          Only include this attribute to indicate that the variable
+          contains the pathname of an input dataset that resides in the
+          CESM inputdata directory tree.  Note that the variables
+          containing the names of restart files that are used in branch
+          runs don't reside in the inputdata tree and should not be given
+          this attribute.
+
+       The recognized values are "abs" to indicate that an absolute
+          pathname is required, or "rel:var_name" to indicate that the
+          pathname is relative and that the namelist variable "var_name"
+          contains the absolute root directory.
+
+     category
+          A category assigned for organizing the documentation.
+
+     group
+          The namelist group that the variable is declared in.
+
+     valid_values
+          This is an optional attribute that is mainly useful for variables
+          that have only a small number of allowed values. It is a
+          comma-separated list of valid values for the variable.
+
+     desc
+          This is a text description of the variable including its
+          purpose and use.
+
+     values
+          This is a grouping of all the cases where a value can be
+          assigned with the namelist generator has been run.
+
+     value
+          Each <value> tag specifies a case where a value is assigned
+          to this variable when the namelist generator is run. If the
+          tag has no attributes, it is a default value. In general,
+          the namelist generator attempts to find a value with the
+          maximium number of attribute matches (and no non-matches).
+
+     standard_name
+          This is the CCPP Standard Name of the variable
+
+     units
+          This is the CCPP unit specification of the variable (e.g., m s-1).
+                                                                        -->
+  <entry id="do_diagnostic_co2">
+    <type>logical</type>
+    <category>coupling</category>
+    <group>surface_coupling_nl</group>
+    <standard_name>do_diagnostic_co2_export_to_coupler</standard_name>
+    <units>flag</units>
+    <desc>
+      Send the atmospheric CO2 volume mixing ratio to the coupler in the
+      diagnostic CO2 field (true) or the prognostic CO2 field (false)
+      Default: true
+    </desc>
+    <values>
+      <value>.true.</value>
+    </values>
+  </entry>
+
+</entry_id_pg>