Using mksurfdata to create surface datasets from grid datasets

Preparing your mksurfdata namelist

When running mksurfdata by hand you will need to prepare your own input namelist. There are sample namelists that are setup for running on the NCAR machine bluefire. You will need to change the filepaths to run on a different machine. The list of sample namelists include

We list the namelist items below. Most of the namelist items are filepaths to give to the input half degree resolution datasets that you will use to scale from to the resolution of your grid dataset. You must first specify the input grid dataset for the resolution to output for:

1. mksrf_fgrid Grid dataset

1. mksrf_ffrac land fraction and land mask dataset

2. mksrf_fglacier Glacier dataset

3. mksrf_flai Leaf Area Index dataset

4. mksrf_flanwat Land water dataset

5. mksrf_forganic Organic soil carbon dataset

6. mksrf_fmax Max fractional saturated area dataset

7. mksrf_fsoicol Soil color dataset

8. mksrf_fsoitex Soil texture dataset

9. mksrf_ftopo Topography dataset (this is used to limit the extent of urban regions and is used for glacier multiple elevation classes)

10. mksrf_furban Urban dataset

11. mksrf_fvegtyp PFT vegetation type dataset

12. mksrf_fvocef Volatile Organic Compound Emission Factor dataset

1. mksrf_fdynuse "dynamic land use" for transient land-use/land-cover changes. This is an ASCII text file that lists the filepaths to files for each year and then the year it represents (note: you MUST change the filepaths inside the file when running on a machine NOT at NCAR). We always use this file, even for creating datasets of a fixed year. Also note that when using the "pft_" settings this file will be an XML-like file with settings for PFT's rather than filepaths (see the Section called Experimental options to mksurfdata below).

1. all_urban If entire area is urban (typically used for single-point urban datasets, that you want to be exclusively urban)

2. mksrf_firrig Irrigation dataset, if you want activate the irrigation model over generic cropland (experimental mode, normally NOT used)

3. mksrf_gridnm Name of output grid resolution (if not set the files will be named according to the number of longitudes by latitudes)

4. mksrf_gridtype Type of grid (default is 'global')

5. nglcec number of glacier multiple elevation classes. Can be 0, 1, 3, 5, or 10. When using the resulting dataset with CLM you can then run with glc_nec of either 0 or this value. (experimental normally use the default of 0, when running with the land-ice model in practice only 10 has been used)

6. numpft number of Plant Function Types (PFT) in the input vegetation mksrf_fvegtyp dataset. You change this to 20, if you want to create a dataset with prognostic crop activated. The vegetation dataset also needs to have prognostic crop types on it as well. (experimental normally not changed from the default of 16)

7. outnc_large_files If output should be in NetCDF large file format

8. outnc_double If output should be in double precision (normally we turn this on)

9. pft_frc array of fractions to override PFT data with for all gridpoints (experimental mode, normally NOT used).

10. pft_idx array of PFT indices to override PFT data with for all gridpoints (experimental mode, normally NOT used).

11. soil_clay percent clay soil to override all gridpoints with (experimental mode, normally NOT used).

12. soil_color Soil color to override all gridpoints with (experimental mode, normally NOT used).

13. soil_fmax Soil maximum fraction to override all gridpoints with (experimental mode, normally NOT used).

14. soil_sand percent sandy soil to override all gridpoints with (experimental mode, normally NOT used).

After creating your namelist, when running on a non NCAR machine you will need to get the files from the inputdata repository. In order to retrieve the files needed for mksurfdata you can do the following on your namelist to get the files from the inputdata repository, using the check_input_data script which also allows you to export data to your local disk.

> cd models/lnd/clm/tools/mksurfdata
# First remove any quotes and copy into a filename that can be read by the
# check_input_data script
> sed "s/'//g" namelist > clm.input_data_list
# Run the script with -export and give the location of your inputdata with $CSMDATA
> ../../../../../scripts/ccsm_utils/Tools/check_input_data -datalistdir . \
-inputdata $CSMDATA -check -export
# You must then do the same with the fdynuse file referred to in the namelist
# in this case we add a file = to the beginning of each line
> awk '{print "file = "$1}' pftdyn_hist_simyr2000-2000.txt > clm.input_data_list
# Run the script with -export and give the location of your inputdata with $CSMDATA
> ../../../../../scripts/ccsm_utils/Tools/check_input_data -datalistdir . \
-inputdata $CSMDATA -check -export

<pft_f>100</pft_f><pft_i>1</pft_i><harv>0,0,0,0,0</harv><graz>0</graz>

Standard Practices when using mksurfdata

In this section we give the recommendations for how to use mksurfdata to give similar results to the files that we created when using it.

If you look at the standard surface datasets that we have created and provided for use, there are three practices that we have consistently done in each (you also see these in the sample namelists and in the mksurfdata.pl script). The first is that we always output data in double precision (hence outnc_double is set to .true.). The next is that we always use the procedure for creating transient datasets (using mksrf_fdynuse) even when creating datasets for a fixed simulation year. This is to ensure that the fixed year datasets will be consistent with the transient datasets. When this is done a "surfdata.pftdyn" dataset will be created -- but will NOT be used in CLM. If you look at the sample namelist mksurfdata.namelist you note that it sets mksrf_fdynuse to the file pftdyn_hist_simyr2000.txt, where the single file entered is the same PFT file used in the rest of the namelist (as mksrf_fvegtyp). The last practice that we always do is to always set mksrf_ftopo, even if glacier elevation classes are NOT active. This is important in limiting urban areas based on topographic height, and hence is important to use all the time. The glacier multiple elevation classes will be used as well if you are running a compset with the active glacier model.

There are two other important practices for creating urban single point datasets. The first is that you often will want to set all_urban to .true. so that the dataset will have 100% of the gridcell output as urban rather than some mix of: urban, vegetation types, and other landunits. The next practice is that most of our specialized urban datasets have custom values for the urban parameters, hence we do NOT want to use the global urban dataset to get urban parameters -- we use a previous version of the surface dataset for the urban parameters. However, in order to do this, we need to append onto the previous surface dataset the grid and land mask/land fraction information from the grid and fraction datasets. This is done in mksurfdata.pl using the NCO program ncks. An example of doing this for the Mexico City, Mexico urban surface dataset is as follows:

> ncks -A $CSMDATA/lnd/clm2/griddata/griddata_1x1pt_mexicocityMEX_c090715.nc \
$CSMDATA/lnd/clm2/surfdata/surfdata_1x1_mexicocityMEX_simyr2000_c100407.nc
> ncks -A $CSMDATA/lnd/clm2/griddata/fracdata_1x1pt_mexicocityMEX_navy_c090715.nc \
$CSMDATA/lnd/clm2/surfdata/surfdata_1x1_mexicocityMEX_simyr2000_c100407.nc

The final issue is how to build mksurfdata. When NOT optimized mksurfdata is very slow, and can take many hours to days to even run for medium resolutions such as one or two degree. So usually you will want to run it optimized. Possibly you also want to use shared memory parallelism using OpenMP with the SMP option. The problem with running optimized is that answers will be different when running optimized versus non-optimized for most compilers. So if you want answers to be the same as a previous surface dataset, you will need to run it on the same platform and optimization level. Likewise, running with or without OpenMP may also change answers (for most compilers it will NOT, however it does for the IBM compiler). However, answers should be the same regardless of the number of threads used when OpenMP is enabled. Note, that the output surface datasets will have attributes that describe whether the file was written out optimized or not, with threading or not and the number of threads used, to enable the user to more easily try to match datasets created previously. For more information on the different compiler options for the CLM4 tools see the Section called Common environment variables and options used in building the FORTRAN tools.