Chapter 3. Adding New Resolutions or New Files to the build-namelist Database

Table of Contents
Managing Your Own Data-files
Adding Resolution Names
Adding or Changing Default Filenames

In the last chapter we gave the details on how to create new files for input into CLM. These files could be either global resolutions, regional-grids or even a single grid point. If you want to easily have these files available for continued use in your development you will then want to include them in the build-namelist database so that build-namelist can easily find them for you. You can deal with them, just by putting the settings in the user_nl_clm namelist file, or by using CLM_USRDAT_NAME. Another way to deal with them is to enter them into the database for build-namelist, so that build-namelist can find them for you. This keeps one central database for all your files, rather than having multiple locations to keep track of files. If you have a LOT of files to keep track of it also might be easier than keeping track by hand, especially if you have to periodically update your files. If you just have a few quick experiments to try, for a short time period you might be best off using the other methods mentioned above.

There are two parts to adding files to the build-namelist database. The first part is adding new resolution names which is done in the models/lnd/clm/bld/namelist_files/namelist_definition_clm4_5.xml file (and in the models/lnd/clm/bld/config_files/config_definition.xml file when adding supported single-point datasets). You can then use the new resolution by using CLM_USRDAT_NAME. If you also want to be able to give the resolution into create_newcase -- you'll need to add the grid to the scripts/ccsm_utils/Case.template/config_grid.xml file.

The second part is actually adding the new filenames which is done in the models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5.xml file (models/lnd/clm/bld/namelist_files/namelist_defaults_clm4_5_tools.xml file for CLM tools). If you aren't adding any new resolutions, and you are just changing the files for existing resolutions, you don't need to edit the namelist_definition file.

Managing Your Own Data-files

If you are running on a supported machine (such as yellowstone or hopper) the standard input datasets will already be available and you won't have to check them out of the subversion inputdata server. However, you also will NOT be able to add your own datafiles to these standard inputdata directories -- because most likely you won't have permissions to do so. In order to add files to the XML database or to use CLM_USRDAT_NAME you need to put data in the standard locations so that they can be found. The recommended way to do this is to use the link_dirtree tool in the CESM scripts. Some information on link_dirtree is available in the CESM1.2.0 Scripts User's Guide. We also have some examples of it's use here and in other sections of this User's Guide.

Using link_dirtree is quite simple, you give the directory where data exists and then the directory that you want to create where datasets will point to the original source files. In the example below we use "$HOME/inputdata", but MYCSMDATA could be any directory you have access to where you want to put your data.

> cd scripts
# First make sure you have a inputdata location that you can write to 
# You only need to do this step once, so you won't need to do this in the future
# (except to bring in any updated files in the original $CSMDATA location).
> setenv MYCSMDATA $HOME/inputdata    # Set env var for the directory for input data
> ./link_dirtree $CSMDATA $MYCSMDATA
Then when you create a case you will change DIN_LOC_ROOT_CSMDATA to point to the location you linked to rather than the default location.


In order to list the files that you have created you merely need to use the UNIX command find to find the files that are NOT softlinks. So for example executing the following command:

> find $MYCSMDATA -type f -print
for me gives the following truncated list of CLM_USRDAT_NAME files that I have created.

You can also use find to list files that have a particular pattern in the name as well (using the -name option with wildcards). Also you can always rerun the link_dirtree command if any new files are added that you need to be linked into your directory tree. Since, the files are soft-links -- it doesn't take up much space other than the files that you add there. This way all of the files are kept in one place, they are organized by usage according to CESM standards, and you can easily find your own files, and CLM can find them as well.