6.2 Adding new history fields

Model history output may appear in two-dimensional grid form or one-dimensional subgrid form (depending on the value of the namelist variable HIST_DOV2XY). One-dimensional subgrid output may in turn appear in gridcell, landunit, column or pft form. History file output is controlled by the files histFileMod.F90 and clmpoint.F90 (in directory main/). The user must modify these two files accordingly in order to add new user-defined history fields to the history tapes. It is assumed in the following that the user is completely familiar with Fortran 90 pointer concepts and syntax.

Module clmpoint.F90 creates arrays of one-dimensional real pointers for selected clmtype components. Each of these arrays has one of the following forms:

real pointers to single level subgrid components:  
      clmpointer(derived_type_name)%val(one_dimensional_index)%rp  

real pointers to multi level subgrid components:  
      clmpointer(derived_type_name)%val(one_dimensional_index)%rap(:)  

The ``derived_type_name'' specifies the particular clmtype derived type component that will be pointed to. The ``one_dimensional_index'' spans the number of model gridcells, landunits, columns or pfts that is appropriate for the derived_type_name. At the top of clmpoint.F90 a default list of ``derived_type_name'' parameter settings is provided. For example, ip_pes_t_ref2m corresponds to the ``derived_type_name'' for the array containing pointers to all pft subgrid level t_ref2m values and one_dimensional_index can have any value from 1 to the number of model subgrid level pfts. Note that the default list of parameter names is much larger than those that are actually used in clmpoint.F90 to set up the pointer arrays.

As a simple illustration, the following example code summarizes how pointer arrays are created and used in clmpoint.F90 (refer to files clmtype.F90 and clm_mapping.F90 for details on clmtype components).

       ! Define clmpointer data structure
     
       type clm_pointer
          type (value_pointer), dimension(:), pointer :: val
       end type clm_pointer
       integer, parameter :: max_mapflds = 500
       type (clm_pointer) :: clmpointer(max_mapflds)
     
       ! Determine ``derived_type_name'' for t_ref2m at the pft level
     
       integer, parameter :: ip_pes_t_ref2m = 1
     
       ! Determine beginning and ending pft 1d indices for the
       ! current task (see clmtype.F90)
       ! pft 1d indices correspond to a one-dimensional vector 
       ! representation of the model subgrid level pft components
     
       begp = pfts1d%beg
       endp = pfts1d%end
     
       ! Allocate memory for t_ref2m pointer array
     
       allocate (clmpointer(ip_pes_t_ref2m)%val(begp:endp))
     
       ! Set up clmpointer array for t_ref2m
       ! ``g'' is a pointer to a model gridcell component
       ! ``l'' is a pointer to a landunit component within gridcell ``g''	
       ! ``c'' is a pointer to a column component within landunit ``l''	
       ! ``p'' is a pointer to a pft component within column ``c''	
       ! ``p%pps'' is the physical state component of pft ``p''
       ! ``p%pps%index1d'' is an index into a one dimensional vector
       ! representation of model subgrid level pft components 
     
       ! Loop over gridcells
       do gi = 1,clm%mps%ngridcells
          g => clm%g(gi)
     
          ! Loop over all landunits in the given gridcell
          do li = 1,g%gps%nlandunits
             l => g%l(li)
     
             ! Loop over all columns in the given landunit
             do ci = 1,l%lps%ncolumns
                c => l%c(ci)
     
                ! Loop over all pfts in the given column
                do pi = 1,c%cps%npfts
                   p => c%p(pi)
                   pindex = p%pps%index1d
     
                   ! Set up pft level pointer array to t_ref2m
                   clmpointer(ip_pes_t_ref2m)%val(pindex)%rp => p%pes%t_ref2m
                end do ! end of PFTs loop

             end do ! end of columns loop
          end do ! end of landunits loop
       end do ! end of gridcells loop

In the above example, pindex spans the total number of model subgrid level pfts for a given task (if MPI is used) or the total number of model subgrid level pfts (if MPI is not used). Setting up the above pointer array is analogous to gathering all the 2m reference temperatures from all the model subgrid level pfts into a single one-dimensional array. History file output is done ONLY via these one dimensional pointer arrays set up in clmpoint.F90.

Module histFileMod.F90 contains routines that create and write model history files and that update the model history buffer during the course of the model simulation. The initialization of history fields is done in subroutine masterlist_build(), whereas the determination of the history fields which are active by default on the various history tapes is performed in subroutine masterlist_change_active().

In masterlist_build(), two entries must be specified for each field: an array hpindices followed by a call to subroutine masterlist_addfld(). The array, hpindices, contains four entries: hpindices(1) corresponds to the gridcell level derived_type_name for the requested field, hpindices(2) is the landunit subgrid level derived_type_name for the field, hpindices(3) is the column subgrid level derived_type_name and hpindices(4) is the pft subgrid level derived_type_name. If the value of an hpindices element is set to -1, one-dimensional output is not permitted for that subgrid type for the given field. Requesting such output will result in model termination. If the value of an hpindices element is set to not_valid, then requesting one-dimensional output for that subgrid type will result in a value of 1.e36 appearing for all the output field values.

As an example, hpindices is set as follows for history field SNOWAGE:

       hpindices = (/-1, -1, ic_cps_snowage, not_valid/)

Consequently, the user may not request one-dimensional gridcell or landunit output for SNOWAGE. If the user requests one-dimensional pft level output for SNOWAGE via the following namelist settings,

       HIST_FINCL2 = 'SNOWAGE' 
       HIST_TYPE1D_PERTAPE(2) = 'PFTS'

each output pft value for SNOWAGE will be 1.e36. Since SNOWAGE is computed in the model as a column property, it makes sense to set its pft derived_type_name to not_valid.

As a second example, the history field, TSA (2m reference temperature) has hpindices set as follows:

       hpindices = (/-1, -1, ic_ces_pes_a_t_ref2m, ip_pes_t_ref2m/)

This implies that one dimensional history output for TSA can occur either on columns or pfts. Gridcell and landunit one dimensional output for this field is not permitted due to the value of -1. Furthermore, one dimensional column output will use the array

       clmpointer(ic_ces_pes_a_t_ref2m)%val(:)%rp.

whereas one dimensional pft output will use the array

       clmpointer(ip_pes_t_ref2m)%val(:)%rp.

Following the setting of hpindices, a call to subroutine masterlist_addfld() must be made specifying required initialization information for a given history field. For example, the following call is made to initialize the 2m reference temperature:

       call masterlist_addfld (fname='TSA', type1d='column', units='K', numlev=1, &
              avgflag='A', long_name='2m air temperature', hpindices=hpindices)

The arguments to the above call are as follows:

       fname     : name of history field
       type1d    : default one dimensional output type 
                   (valid values are ``gridcell'',''landunit'',''column'' or ``pft'')
       units     : field units
       numlev    : number of vertical values
       avgflag   : default time averaging flag
                   (valid values are ``A''(average), ''I''(instantaneous),
                   ''M''(minimum) or ``X''(maximum))
       long_name : descriptive name of history field
       hpindices : array of one dimensional output parameter names.

It is important to note that if the namelist variable HIST_DOV2XY is set to true, history output will appear in two dimensional grid form. Two-dimensional grid output will be obtained by calculating grid cell averages from the ``type1d'' subgrid components.

The following lists steps that must be taken by the user to add a new history field to the model. Currently, the upward longwave radiation above the canopy is not output to the history file. We assume that the user wants to add this field to the history output at either the column or pft subgrid level. The following steps assume that a clmpointer array does not exist for the desired history variable. Steps 1 and 2 below discuss how such a pointer array is created. If a clmpointer array already exists for the needed history variable then only steps 4 and 5 are needed. Step 3 is needed only if 1d output is requested at a subgrid level where spatial averaging is required and that spatial averaging is not currently in the code.

1. Currently, parameter values for the derived_type_names of column and pft level upward longwave radiation are already contained at the top of clmpoint.F90 (ip_pef_ulrad and ic_cef_pef_a_ulrad). If these parameters did not already exist, they would have to be added to the list of existing parameter values.

2. The following code fragments should be added to subroutine clmpoint_init() in module clmpoint.F90.

   ! Add code to allocate memory for pft level pointer array 
   ! for upward longwave radiation
   
   allocate (clmpointer(ip_pef_ulrad)%val(begp:endp))
   
   ! Add code to allocate memory for column level pointer array 
   ! for upward longwave radiation
   
   allocate (clmpointer(ic_cef_pef_a_ulrad)%val(begc:endc)) 
   
   ! Add code to set up column and pft level clmpointer arrays for
   ! upward longwave history output
   ! ``g'' is a pointer to a model gridcell component
   ! ``l'' is a pointer to a landunit component within gridcell ``g''	
   ! ``c'' is a pointer to a column component within landunit ``l''	
   ! ``c%cps'' is the physical state component of column ``c''
   ! ``c%cps%index1d'' is an index into a one dimensional vector
   ! representation of model subgrid level column components 
   ! ``p'' is a pointer to a pft component within column ``c''	
   ! ``p%pps'' is the physical state component of pft ``p''
   ! ``p%pes'' is the energy state component of pft ``p''
   ! ``p%pps%index1d'' is an index into a one dimensional vector
   ! representation of model subgrid level pft components 
   
   ! Loop over gridcells
   do gi = 1,clm%mps%ngridcells
      g => clm%g(gi)
   
      ! Loop over all landunits in the given gridcell
      do li = 1,g%gps%nlandunits
         l => g%l(li)
   
        ! Loop over all columns in the given landunit
         do ci = 1,l%lps%ncolumns
            c => l%c(ci)
            cindex = c%cps%index1d
   
            ! Set up column level pointer array 
            clmpointer(ic_cef_pef_a_ulrad)%val(cindex)%rp => c%cef%pef_a%ulrad
   
            ! Loop over all pfts in the given column
            do pi = 1,c%cps%npfts
               p => c%p(pi)
               pindex = p%pps%index1d
   
               ! Set up pft level pointer array 
               clmpointer(ip_pef_ulrad)%val(pindex)%rp => p%pef%ulrad
   
            end do ! end of PFTs loop
         end do ! end of columns loop
      end do ! end of landunits loop
   end do ! end of gridcells loop
   

3. Currently, the model calculates the upward longwave radiation at both the pft and column subgrid level. Pft level values are obtained in module CanopyFluxesMod.F90 whereas column level values are calculated in module pft2columnMod.F90.

4. The following statements should be added to subroutine masterlist_build() (in module histFileMod.F90):

   hpindices = (/-1, -1, ic_cef_pef_a_ulrad, ip_pef_ulrad/)
   call masterlist_addfld (fname='ULRAD', type1d='pft', units='W/m2',
          numlev=1, avgflag='A', long_name='upward longwave radiation above canopy', 
          hpindices=hpindices)
   

   Note that setting type1d to 'pft' above will result in default 1d output on the pft subgrid level for the history field 'ULRAD'.
5. The following statement should be added to subroutine masterlist_change_active() (in module histFileMod.F90) if the user wants this field on the primary tape by default:

   call masterlist_make_active (name='ULRAD', tape_index=1)