5. Controlling output from CISM and CLM

5.1. Controlling CISM output

The default CISM output frequency is yearly. Most of the CISM output fields are instantaneous, so this default frequency means that you get a snapshot of the current state at the end of each year. You can change the output to be less frequent via the namelist variable history_frequency, which can be set in user_nl_cism. For example, to give output every 10 years, set:

history_frequency = 10

The set of variables written to each history file is controlled by the namelist variable cesm_history_vars. To see the variables output by default, examine CaseDocs/cism_in after running preview_namelists for your case. Among the standard fields written to the history file are the ice thickness (thk), upper surface elevation (usurf), bedrock elevation (topg), and the surface mass balance (smb) and surface temperature (artm) downscaled to the ice sheet grid.

To modify the list of history fields, set cesm_history_vars in user_nl_cism. The source files with names *_io.F90.default specify the fields than can be written out: for CESM, these get copied to files with the same name but with the .default stripped off. The easiest way to write out new variables for your case is to add them to a file ending in vars.def and then rebuild the *_io.F90 files using a python script. The necessary script can be found in $CASEROOT/Buildconf/cismIOconf. See the README.cismIO file in that directory for details.

Model restart frequency is coordinated by the CESM coupler. The restart file contains all the fields required for exact restart. However, the restart will be exact only if the file is written immediately after an ice dynamics time step. This will normally be the case for restart files written at the end of any model year.

5.2. Producing land ice-specific output from CLM

5.2.1. Outputting forcing fields sent from CLM to CISM

CLM sends two sets of fields to CISM for each elevation class: qice and tsrf. In addition, it sends a third set of fields to the coupler for downscaling purposes: topo. It can often be useful to view the values of these forcing fields for each elevation class within each grid cell. To do this, you can use the three CLM history variables, QICE_FORC, TSRF_FORC and TOPO_FORC. These history variables are inactive by default, but can be added to any of CLM’s history files using the hist_fincl CLM namelist variables. For example, to add QICE_FORC and TSRF_FORC to CLM’s default (monthly) history file, you would add the following in user_nl_clm:

hist_fincl1 = 'QICE_FORC','TSRF_FORC'

As with other CLM history variables, additional history files can be created with different time frequencies. See the CLM User’s Guide for details on how to do this.

5.2.2. Adding a CLM history field that provides averages only over ice

In general, CLM history fields give weighted averages over the entire grid cell. If you are interested in diagnostics just over ice landunits for certain history fields, you can make a source code modification for each field of interest.

CLM history field definitions are distributed throughout the CLM source code. The first step is to find the hist_addfld1d or hist_addfld2d subroutine call for the history field(s) of interest, by searching the code for the history field name. Then add a new hist_addfld1d or hist_addfld2d call that is mostly the same as the original, but:

  1. Change the field name (fname), for example, changing TSOI to TSOI_ICE
  2. Change long_name to call out that this field just applies over ice landunits
  3. Add a new argument to the call: l2g_scale_type='ice'.
  4. Possibly add default='inactive' so that this field only appears if explicitly requested in user_nl_clm.

Here are some examples of currently-defined _ICE fields and their non-_ICE counterparts:

call hist_addfld2d (fname='TSOI',  units='K', type2d='levgrnd', &
     avgflag='A', long_name='soil temperature (vegetated landunits only)', &
     ptr_col=this%t_soisno_col, l2g_scale_type='veg')

call hist_addfld2d (fname='TSOI_ICE',  units='K', type2d='levgrnd', &
     avgflag='A', long_name='soil temperature (ice landunits only)', &
     ptr_col=this%t_soisno_col, l2g_scale_type='ice')

call hist_addfld1d (fname='FSH', units='W/m^2',  &
     avgflag='A', long_name='sensible heat not including correction for land use change and rain/snow conversion', &
     ptr_patch=this%eflx_sh_tot_patch, c2l_scale_type='urbanf')

call hist_addfld1d (fname='FSH_ICE', units='W/m^2',  &
     avgflag='A', &
     long_name='sensible heat not including correction for land use change and rain/snow conversion (ice landunits only)', &
     ptr_patch=this%eflx_sh_tot_patch, c2l_scale_type='urbanf', l2g_scale_type='ice', &
     default='inactive')

Note that there are already many _ICE fields defined in the code, but many of these are inactive by default (meaning that they need to be explicitly added to history field lists via CLM’s hist_fincl mechanism).