History output on the model grid may appear in either xy grid form or native subgrid form (i.e., as one-dimensional gridcell, landunit, column or PFT output). The output format is controlled by the value of the namelist variable HIST_DOV2XY.
The interface to add history output fields in file histFldsMod.F90 assumes that all arguments occur as keyword-value pairs. The interface also assumes that each field to be added is associated with either a gridcell, landunit, column or PFT level data structure component that has already been defined in clmtype (Section A.47). History fields are either single-level or multi-level fields. A single-level field will have either the total number of model PFTs, columns, landunits or gridcells as its only non-time dimension. A multi-level field will have the number of model PFTs, columns, landunits or gridcells as one non-time dimension, along with a level field (e.g., number of soil levels) as a second non-time dimension.
To add a single-level history output field, a call to add_fld1d (Section A.57.22) needs to be added to routine initHistFlds (Section A.58.1) in module histFldsMod (Section A.58). Similarly, to add a multi-level history output field, a call to subroutine add_fld2d (Section A.57.23) needs to be added to initHistFlds. We describe the formats of calls to add_fld1d and add_fld2d via concrete examples in routine inithistFlds.
A single-level history field, FCEV, is added to the history output via the following call:
call add_fld1d (fname='FCEV', units='watt/m^2', &
avgflag='A', long_name='canopy evaporation', &
ptr_pft=clm3%g%l%c%p%pef%eflx_lh_vege, set_lake=0._r8)
fname
history file field name
long_name
descriptive name of field
units
units of field
avg flag
time averaging flag
valid values are "X" (maximum over time), "A" (time average),
"M" (minimum over time) or "I" (instantaneous)
ptr_pft or ptr_col or ptr_lunit or ptr_gridcell
pointer to clmtype PFT, column, landunit or gridcell
arrays
set_lake
value to set lake points to (optional)
if this value is not set, it is assumed that the model will
provide valid values for the field over lake points
Note that ptr_pft corresponds to the subgrid level at which the canopy evaporation, eflx_lh_vege, is defined in clmtype (Section A.47). Since the canopy evaporation is defined at the PFT level in clmtype, a PFT level pointer, ptr_pft, needs to be declared in the call to add_fld1d. Alternatively, since the snow height, SNOWDP, is defined at the column level in clmtype, the following interface call is used to add this single-level field to the history output:
call add_fld1d (fname='SNOWDP', units='m', &
avgflag='A', long_name='snow height', &
ptr_col=clm3%g%l%c%cps%snowdp)
If a multi-level field is to be added to the history output, the following type of call needs to be added to add_fld2d:
call add_fld2d (fname='H2OSOI', units='mm3/mm3', type2d='levsoi', &
avgflag='A', long_name='volumetric soil water', &
ptr_col=clm3%g%l%c%cws%h2osoi_vol)
fname
history file field name
long_name
descriptive name of field
units
units of field
type2d
second-dimension output type - valid values are
'levsoi', 'levlak', or 'numrad'
avg flag
time averaging flag
valid values are "X" (maximum over time), "A" (time average),
"M" (minimum over time) or "I" (instantaneous)
ptr_pft or ptr_col or ptr_lunit or ptr_gridcell
pointer to clmtype PFT, column, landunit or gridcell
arrays
set_lake
value to set lake points to (optional)
if this value is not set, it is assumed that the model will
provide valid values for the field over lake points
here it is set to zero, but it could also be set to a
missing value (1.e36)
The call to add_fld1d or add_fld2d must include either ptr_pft, ptr_col, ptr_lunit, or ptr_gcell as an argument. The output name of the field (fname), a descriptive name (long_name), the field units (units), the output type of time averaging that will be used for the field must also be provided as arguments. Finally, an optional argument, set_lake, is provided to specify masking values over lake.