Initial Datasets

In addition to the periodic generation of restart files, and depending on the setting of the namelist variable HIST_CRTINIC, CLM3.0 also periodically produces netCDF initial files containing instantaneous variable data in the native subgrid form. The output dimension of each dataset variable corresponds to its dimensionality when it is defined in clmtype (Section A.47).

If, at startup, a new CLM case uses the initial dataset produced by a reference case (via the setting of the namelist variable FINIDAT), the model will not continue in a bit-for-bit fashion with respect to the reference case. The resulting climate, however, should be continuous as long as the namelist or source code is not changed when compared to the reference case. Initial dataset files are smaller and more flexible than binary restart files and are used in cases where it is not crucial for the new run to be bit-for-bit the same as the run which produced the initial files. Since certain model variables take relatively long to spin up (e.g., soil and snow related variables), the use of an initial dataset ensures faster spin up of the model than using arbitrary initialization. Furthermore, since initial files have a self-describing format, multiple versions of the model code can use a given initial dataset. Restart files, on the other hand, may change frequently during model development and are often difficult to use with different versions of the code.

All initial dataset logic is contained in the file inicFileMod.F90. Routine inicfile (Section A.61.1) controls the top level logic to create or read from an initial dataset depending on the value of the input argument flag. Routine inicfields (Section A.61.2) actually performs the write to or read from the initial dataset.

If new variables are to be added to the initial dataset, the user must modify routine inicfields (Section A.61.2). We provide several illustrative examples currently in inicfields (Section A.61.2) of the interface usage needed to add both single-level and multi-level variables to the initial dataset.

To add a new field to the initial dataset, a call must be made to ncd_defvar (Section A.78) to define the field followed by a call to ncd_iolocal (Section A.78) to read or write the field. The total set of initial dataset fields are defined, written out or read in via calls to inicfields (Section A.61.2) with flag set to 'define', 'write' or 'read', respectively.

The following call to ncd_defvar is made to define the single-level initial dataset field, T_GRND:

       call ncd_defvar(ncid=ncid, varname='T_GRND', xtype=nf_double,  &
            dim1name='column', long_name='ground temperature', units='K')
 
       ncid  
           netcdf file id 

       varname 
           variable name 
 
       xtype
           output netCDF type (nf_int or nf_double) 

       dim1name
           subgrid dimension: 'pft', 'column', 'landunit', or 'gridcell' 

       long_name
           variable descriptive name (optional)

       units
           variable units (optional)

Subsequently, T_GRND is written to or read from the initial dataset field via the following call to ncd_iolocal:

       call ncd_iolocal(varname='T_GRND', data=cptr%ces%t_grnd, 
            datadim1='column', &
            ncid=ncid, flag=flag, readvar=readvar)
       if (flag=='read' .and. .not. readvar) call endrun()

       ncid  
           netcdf file id 

       flag
          'read' or 'write' 

       varname
           variable name 

       data
           pointer to clmtype PFT, column, landunit or gridcell array 

       datadim1
           subgrid dimension: 'pft', 'column', 'landunit', or 'gridcell' 
 
       readvar
           only relevant when flag is set to 'read' 
           used to determine action if variable is not on the initial dataset

Note that if flag is set to 'read', a check is made after the call to ncd_iolocal to determine if the variable is on the initial dataset. For most variables, the model will stop if the variable is not present. The user can change this logic, however, to provide default values for user added variables if they are not present on the initial dataset.

Similarly, the following call to ncd_defvar is made to define the multi-level initial dataset field, H2OSOI_LIQ:

       call ncd_defvar(ncid=ncid, varname='H2OSOI_LIQ', xtype=nf_double,  &
            dim1name='column', dim2name='levtot', long_name='liquid water', units='kg/m2')

       ncid  
           netcdf file id 

       varname 
           variable name 
 
       xtype
           output netCDF type (nf_int or nf_double) 

       dim1name
           subgrid dimension: 'pft', 'column', 'landunit', or 'gridcell' 

       dim2name
           level dimension: 'levtot', 'levlak' or 'levsno' 
 
       long_name
           variable descriptive name (optional)

       units
           variable units (optional)

with the accompanying call to ncd_iolocal to read/write the field:

       call ncd_iolocal(varname='H2OSOI_LIQ', data=cptr%cws%h2osoi_liq, 
            datadim1='column', datadim2='levtot', &
            ncid=ncid, flag=flag, readvar=readvar)
       if (flag=='read' .and. .not. readvar) call endrun()

       ncid  
           netcdf file id 

       flag
          'read' or 'write' 

       varname
           variable name 

       data
           pointer to clmtype PFT, column, landunit or gridcell array 

       datadim1
           subgrid dimension: 'pft', 'column', 'landunit', or 'gridcell' 
 
       datadim1
           level dimension for variable: 'levtot', 'levlak' or 'levsno' 

       readvar
           only relevant when flag is set to 'read' 
           used to determine action if variable is not on the initial dataset