CUG 6.21 DRIVER How do I pass in new fields between components

In CESM, coupler code has been improved in order to remove the need to change any coupler code when adding the exchange of new fields between model components. To accomplish this, a new standardized naming convention has been introduced for field names that are exchanged between model components. This is summarized below.

====================================================================
   New standardized naming convention
====================================================================
  
  ---------
  definitions:
  ---------
  state-prefix
    first 3 characters: Sx_, Sa_, Si_, Sl_, So_ 
    one letter indices: x,a,l,i,o,s,g,r 
    x => coupler (mapping, merging, atm/ocn flux calc done on coupler procs)
    a => atm
    l => lnd
    i => ice
    o => ocn
    g => glc
    s => snow (from clm to glc)
    r => rof

  state-name 
    what follows state prefix

  flux-prefix
    first 5 characters: Flmn__ 
    lm => between components l and m
    n  => computed by component n
    example: Fioi => ice/ocn flux computed by ice
    example: Fall => atm/lnd flux computed by lnd
    If flux prefix has first letter of P (so first five characters are PFlmn_)
    then flux is passed straight through without scaling by the corresponding fraction)
    
  flux-name
    what follows flux-prefix

  ---------
  rules:
  ---------
  1) states: 
     a) atm attributes fields that HAVE a state-prefix of Sx_ in seq_flds_x2a_states
        rule: will merge all identical values of the state-names from
           seq_flds_i2x_states 
           seq_flds_l2x_states 
           seq_flds_o2x_states 
           seq_flds_xao_states
         to obtain output state-name in seq_flds_x2a_states
  
        rule: to merge input states that originate in the 
           lnd (l2x_a) will be scaled by the lndfrac
           ice (i2x_a) will be scaled by the icefrac
           cpl (xao_a) will be scaled by the ocnfrac
           ocn (o2x_a) will be scaled by the ocnfrac
  
        example: 
           seq_flds_l2x_states = "Sl_t"
           seq_flds_i2x_states = "Si_t"
           seq_flds_o2x_states = "So_t"
           seq_flds_x2a_states = "Sx_t" 
           attribute fields Sl_t, Si_t, So_t, in 
           attribute vectors l2x_a, i2x_a, o2x_a will be
           merged to obtain attribute Sx_t in attribute vector x2a_a
  
     b) atm attribute fields that DO NOT HAVE a state-prefix of Sx_ in seq_flds_x2a_states
        rule: copy directly all variables that identical state-prefix 
               AND state-name in
           seq_flds_i2x_states and seq_flds_x2a_states
           seq_flds_l2x_states and seq_flds_x2a_states
           seq_flds_o2x_states and seq_flds_x2a_states
           seq_flds_xao_states and seq_flds_x2a_states
  
        example 
           seq_flds_i2x_states = ":Si_snowh"
           seq_flds_x2a_states = ":Si_snowh"
           attribute field of Si_snowh in i2x_a will be copied to 
           attribute field Si_snowh in x2a_a
  
  2) fluxes: 
     rule: will merge all identical values of the flux-names from
         seq_flds_i2x_states 
         seq_flds_l2x_states 
         seq_flds_o2x_states 
         seq_flds_xao_states
       to obtain output state-name in seq_flds_x2a_states
  
     rule: input flux fields that originate in the 
         lnd (l2x_a) will be scaled by the lndfrac
         ice (i2x_a) will be scaled by the icefrac
            - ignore all fluxes that are ice/ocn fluxes (e.g. Fioi_)
         cpl (xao_a) will be scaled by the ocnfrac
         ocn (o2x_a) will be scaled by the ocnfrac+icefrac

====================================================================

   New user specified fields
 
====================================================================
 New fields that are user specidied can be added as namelist variables
 by the user in the cpl namelist seq_flds_user using the namelist variable
 array cplflds_customs. The user specified new fields must follow the
 above naming convention.
 As an example, say you want to add a new state 'foo' that is passed 
 from the land to the atm - you would do this as follows 
    apos;seq_flds_user
       cplflds_custom = 'Sa_foo->a2x', 'Sa_foo->x2a'
    /
 This would add the field 'Sa_foo' to the character strings defining the 
 attribute vectors a2x and x2a. It is assumed that code would need to be 
 introduced in the atm and land components to deal with this new attribute 
 vector field.
 Currently, the only way to add this is to edit $CASEROOT/user_nl_cpl
====================================================================

   Coupler fields use cases

====================================================================
 Previously, new fields that were needed to be passed between components
 for certain compsets were specified by cpp-variables. This has been 
 modified to now be use cases. The use cases are specified in the 
 namelist cpl_flds_inparm and are currently triggered by the xml 
 variables CCSM_VOC, CCSM_BGC and GLC_NEC.  
====================================================================