# Adding New Resolutions or New Files to the build-namelist Database

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 editing your namelist by hand (or using a &usernlclm; namelist file), or by using &CLMUSRDAT;. 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.xml` file (and in the `models/lnd/clm/bld/config_files/config_definition.xml` file when adding supported single-point datasets). The second part is actually adding the new filenames which is done in the `models/lnd/clm/bld/namelist_files/namelist_defaults_clm.xml` file (`models/lnd/clm/bld/namelist_files/namelist_defaults_clm_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 bluefire or jaguar) 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 &CLMUSRDAT; 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 &cesmrel; 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.

    > ./xmlchange -file env_run.xml -id DIN_LOC_ROOT_CSMDATA -val $MYCSMDATA

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 list of &CLMUSRDAT; files that I have created.

    /blhome/erik/inputdata/atm/cam/chem/trop_mozart_aero/aero/aerosoldep_monthly_1849-2006_1x1pt_US-Ha1.nc
    /blhome/erik/inputdata/atm/cam/chem/trop_mozart_aero/aero/aerosoldep_monthly_1849-2006_13x12pt_f19_alaskaUSA.nc
    /blhome/erik/inputdata/atm/cam/chem/trop_mozart_aero/aero/aerosoldep_rcp8.5_monthly_1850-2100_13x12pt_f19_alaskaUSA.nc
    /blhome/erik/inputdata/atm/cam/chem/trop_mozart_aero/aero/aerosoldep_rcp4.5_monthly_1850-2100_13x12pt_f19_alaskaUSA.nc
    /blhome/erik/inputdata/atm/datm7/domain.clm/domain.lnd.1x1pt_US-Ha1_USGS.nc
    /blhome/erik/inputdata/atm/datm7/domain.clm/domain.lnd.13x12pt_f19_alaskaUSA_gx1v6.nc
    /blhome/erik/inputdata/lnd/clm2/griddata/fracdata_13x12pt_f19_alaskaUSA_gx1v6.nc
    /blhome/erik/inputdata/lnd/clm2/griddata/fracdata_1x1pt_US-Ha1_USGS.nc
    /blhome/erik/inputdata/lnd/clm2/griddata/topodata_13x12pt_f19_alaskaUSA.nc
    /blhome/erik/inputdata/lnd/clm2/griddata/griddata_1x1pt_US-Ha1.nc
    /blhome/erik/inputdata/lnd/clm2/griddata/griddata_13x12pt_f19_alaskaUSA.nc
    /blhome/erik/inputdata/lnd/clm2/surfdata/surfdata_13x12pt_f19_alaskaUSA_simyr1850.nc
    /blhome/erik/inputdata/lnd/clm2/surfdata/surfdata_1x1pt_US-Ha1_simyr2000.nc
    /blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_rcp4.5_13x12pt_f19_alaskaUSA_simyr1850-2100.nc
    /blhome/erik/inputdata/lnd/clm2/surfdata/surfdata_1x1pt_US-Ha1_simyr1850.nc
    /blhome/erik/inputdata/lnd/clm2/surfdata/surfdata_13x12pt_f19_alaskaUSA_simyr2000.nc
    /blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_1x1pt_US-Ha1_simyr1849-2006.nc
    /blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_13x12pt_f19_alaskaUSA_simyr1850-2100.nc
    /blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_rcp8.5_13x12pt_f19_alaskaUSA_simyr1850-2100.nc
    /blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_13x12pt_f19_alaskaUSA_simyr1849-2006.nc
    /blhome/erik/inputdata/lnd/clm2/surfdata/surfdata.pftdyn_1x1pt_US-Ha1_simyr1850-2100.nc

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.

## Adding Resolution Names

If you are adding files for new resolutions which aren't covered in the namelist_definition file -- you'll need to add them in. The list of valid resolutions is in the id="res" entry in the `models/lnd/clm/bld/namelist_files/namelist_definition.xml` file. You need to choose a name for your new resolution and simply add it to the comma delimited list of valid_values for the id="res" entry. The convention for global Gaussian grids is number_of_latitudes x number_of_longitudes. The convention for global finite volume grids is latitude_grid_size x longitude_grid_size where latitude and longitude is measured in degrees. For regional or single-point datasets the names have a grid size number_of_latitudes x number_of_longitudes followed by an underscore and then a descriptive name such as a City name followed by an abbreviation for the Country in caps. The only hard requirement is that names be unique for different grid files. Here's what the entry for resolutions looks like in the file:

    <entry id="res" type="char*30" category="default_settings"
           group="default_settings"
           valid_values=
    "128x256,64x128,48x96,32x64,8x16,94x192,0.23x0.31,0.47x0.63,
    0.9x1.25,1.9x2.5,2.65x3.33,4x5,10x15,5x5_amazon,
    1x1_camdenNJ,1x1_vancouverCAN,1x1_mexicocityMEX,1x1_asphaltjungleNJ,
    1x1_brazil,1x1_urbanc_alpha,0.5x0.5">
    Horizontal resolutions
    </entry>

As you can see you just add your new resolution names to the end of the valid_values list.

When using &ptclm; and adding supported single-point resolutions, you'll also want to add these resolutions to the `models/lnd/clm/bld/config_files/config_definition.xml` under the `sitespf_pt` name. The entry in that file looks like:

    <entry id="sitespf_pt"
    valid_values="none,1x1_brazil,5x5_amazon,
    1x1_camdenNJ,1x1_vancouverCAN,1x1_mexicocityMEX,1x1_asphaltjungleNJ,
    1x1_urbanc_alpha,1x1_numaIA,1x1_smallvilleIA"
    value="none" category="physics">
    Flag to turn on site specific special configuration flags for supported single
    point resolutions.
    Currently the only special settings are for MEXICOCITY and VANCOUVER, which make
    changes to urban parameters.
    </entry>

&ptclm; assumes that any supported single-point resolutions are valid settings for `sitespf_pt`.

## Adding or Changing Default Filenames

To add or change the default filenames you edit the `models/lnd/clm/bld/namelist_files/namelist_defaults_clm.xml` and either change an existing filename or add a new one. Most entries in the default namelist files, include different attributes that describe the different properties that describe the differences in the datasets. Attributes include the: resolution, year to simulation, range of years to simulate for transient datafiles, the land-mask, the representative concentration pathway (rcp) for future scenarios, and the type of biogeochemistry (bgc) model used. For example the `fatmgrid` for the 1.9x2.5 resolution is as follows:

    <fatmgrid hgrid="1.9x2.5" >lnd/clm2/griddata/griddata_1.9x2.5_060404.nc
    </fatmgrid>

Other `fatmgrid` files are distinguished from this one by their resolution (hgrid) attribute.

To add or change the default filenames for &clm; tools edit the `models/lnd/clm/bld/namelist_files/namelist_defaults_clm_tools.xml` and either change an existing filename or add a new one. Editing this file is similar to the `namelist_defaults_clm.xml` talked about above.

### What are the required files?

Different types of simulations and different types of configurations for &clm; require different lists of files. The Carbon Nitrogen (cn) Biogeochemistry model for example requires `stream_fldfilename_ndep` files, which are NOT required by other bgc modes. Transient simulations also require transient datasets, and the names of these datasets are sometimes different from the static versions (sometimes both are required as in the dynamic PFT cases).

In the following table we list the different files used by CLM, they are listed in order of importance, dependencies, and customizing. So the required files are all near the top, and the files used only under different conditions are listed later, and files with the fewest dependencies are near the top, as are the files that are least likely to be customized.

#### Required Files for Different Configurations and Simulation Types

Filename | Config. type | Simulation type | Resol. Dependent? | Other Dependencies?
--- | --- | --- | --- | ---
Notes
fpftcon | ALL | ALL | No | No
Not usually customized, as describes plant function type properties. &ptclm; copies the file for you so that you can customize it if you like, see .
fsnowoptics | ALL | ALL | No | No
Not usually customized as describes global snow optical properties.
fsnowaging | ALL | ALL | No | No
Not usually customized as describes global snow aging properties.
fatmgrid | ALL | ALL | Yes | No
Creating, using `mkgriddata` usually gives you the amount of customization you need, as it just describes the grid and grid extents.
fatmlndfrc | ALL | ALL | Yes | land-mask
Describes the land-mask for points with active land, as well as the fraction of each grid-cell covered by land. You might customize it to make sure the land-fraction of your grid-cell matches the expected values for your site. But, usually you will just use what mkgriddata gives you.
fsurdat | ALL | ALL | Yes | simulation-year

Describes percentages of different land-units, columns and vegetation types within each grid-cell. To customize for a specific point or region you may want to use custom input datasets to `mksurfdata` when creating the file. `mksurfdata` also allows you to customize the PFT, and soil types to it see . &ptclm; takes advantage of this to create customized datasets as well, see the chapter on &ptclm; at .

flanduse_timeseries | ALL | transient land-use land-cover change | Yes | Simulation year range, and representative concentration pathway (rcp)
See notes on fsurdat files.
frivinp_rtm | RTM only | ALL | No | No
We only provide a half-degree global river routing file. If you want to model river flow for a smaller scale, or a basin regional scale, you would need to create your own custom file to do that. Normally, we turn river-routing OFF for regional or single point simulations.
finidat | ALL | RUN_TYPE="startup", CLM_FORCE_COLDSTART="off" | Yes | mask, maxpft, bgc, simulation-year, start-date
Used for starting the model from a spun-up state. Create these files by running the model for multiple years and saving the restart file from the end of a spin-up simulation.
stream_fldfilename_ndep | bgc=cn/cndv | Yes | No | simulation-year
You may customize this file to get the Nitrogen deposition characteristics of your site if available. This file will be interpolated while the model is running from it's resolution to the resolution that &clm; is running at.