A list of high resolution ``raw'' datasets is provided with the CLM2.0 distribution. These raw datasets are only needed if a raw surface dataset is to be created at runtime (see CLM2.0 User's Guide). The following is a list of these datasets:
The user has the option of replacing any of these raw datasets, as long as the structure of the netCDF files is preserved. A series of fortran routines to convert ascii to raw netCDF data is provided in the directory, /tools/convert_ascii. Alternatively, the user may wish to modify the model surface data directly as long as the original netCDF file structure is preserved.
To output a history field which has not been included in the CLM2.0 code,
the user must do the following:
Step 1. Add the appropriate initialization call for the required history field in subroutine histlst. For example, the following lines could be added in histlst:
call histfldini(nflds, 'NEWFLD ', 'UNITS', nsing, naver,'FIELD DESC', .true., histfld)
Step 2. In subroutine histUpdate, add the following lines (using
the following only as an example):
!$OMP PARALLEL DO PRIVATE (K)
do k = begpatch,endpatch
tmpslev(k) = call histslf('NEWFLD', tmpslev)
end do
where tmpslev and histslf are used for adding a new single-level field (whereas tmpmlev and histmlf are used for adding a new multi-level field). If adding a multi level field, the call to histmlf passes an additional variable denoting the number of levels (nlevsoi or nlevlak). It may also be necesasry to increase the maximum allowable number of single level fields. This can be done by increasing the values of the parameters max_slevflds or max_mlevflds in routine src/main/clm_varpar.F90.
Initial datasets are created by the land model periodically (for details, see the CLM2.0 User's Guide). Initial datasets are netCDF files containing instantaneous variable data. Since certain model variables take relatively long to spin up (e.g. soil and snow related variables), using an initial dataset ensures faster spin up of the model than using arbitrary initialization. The variables stored in initial dataset files are dimensioned by number of landpoints (e.g., numland = 1956 for a T31 global resolution) and the maximum number of subgrid patches in a land gridcell (maxpatch = 8). If a variable has multiple vertical levels, an additional dimension (e.g. nlevsoi = 10) is used.
Changing an initial dataset should not be necessary most of the time. However, if new variables must be added to the initial dataset, the user should refer to subroutines inicwrt and inicrd in the file src/main/inicFileMod.F90. The user should start in subroutine inicwrt by defining the new variable as a single or multi-level field (exactly as is done for existing variables). In the same subroutine the user should add a few lines to write out the new variable (again as done for existing variables). Subsequently, the user should add a similar group of lines to subroutine inicrd, for the variable to be recognized by the code at initialization. Comments in the code are clear for the user to identify where variables are defined, where they are written, and where they are read.
An important distinction between initial and restart files is that initial files have a self-describing format (since they are netCDF), and therefore may be used by future versions of the model to initialize a simulation. Restart files (see below), on the other hand, may change frequently during model development and may be difficult to use with different versions of the code.
Restart files contain instantaneous binary data for a set of time-dependent variables. The data is stored in binary format to ensure bit-for-bit agreement with a terminated run which was subsequently restarted. Restart files contain a version number to ensure that the code being used is compatible with the restart file being read. If the user modifies the contents of the restart file, the version number should be incremented.
Restart files should be used to extend previously started simulations or to branch from one simulation to another in which history file namelist variables have been modified. For a branch run, the user must change the simulation's case name.
The criterion for a ``successful restart'' is that the model has available exactly the same information upon restart that it would have had if it had not stopped. Restart files may need to be modified during model development to include new time-dependent variables. A simple rule is that if a run produces even slightly different answers when restarted compared to when left uninterrupted, then certain variables are missing from the restart file.
Restart files are written in subroutine restwrt and read in subroutine restrd (which are contained in file src/main/restFileMod.F90. Subroutine restrd reads the data in exactly the same order as it was written out and the simulation continues as though uninterrupted. If a user modifies the code such that it becomes necessary to add a new variable to the restart file, separate entries must be made in subroutines restwrt and restrd. As an example, if the following field were to be added the the restart file, the following two entries would have to be made:
restwrt:
buf1d(begpatch:endpatch) = clm(begpatch:endpatch)%newvar
call wrtout (nio, buf1d)
restrd:
call readin (nio, buf1d)
clm(begpatch:endpatch)%newvar = buf1d(begpatch:endpatch)
The user must make sure to place the former two lines in exactly the same order with respect to existing variables as the latter two lines. For example, variable fwet is between variables t_grnd and tlai in both subroutines restrd and restwrt.