1.3.5. Creating Surface Datasets

When just creating a replacement file for an existing one, the relevant tool should be used directly to create the file. When you are creating a set of files for a new resolution there are some dependencies between the tools that you need to keep in mind when creating them. The main dependency is that you MUST create a SCRIP grid file first as the SCRIP grid dataset is then input into the other tools. Also look at Table 3-1 which gives information on the files required and when. Figure 1.3.2 shows an overview of the general data-flow for creation of the fsurdat datasets.

../../_images/mkmapdata_mksurfdata.jpeg

Figure 1.3.2 Data Flow for Creation of Surface Datasets from Raw SCRIP Grid Files

Starting from a SCRIP grid file that describes the grid you will run the model on, you first run mkmapdata.sh to create a list of mapping files. See Figure 1.3.1 for a more detailed view of how mkmapdata.sh works. The mapping files tell mksurfdata_map how to map between the output grid and the raw datasets that it uses as input. The output of mksurfdata_map is a surface dataset that you then use for running the model.

Figure 1.3.3 is the legend for this figure (Figure 1.3.2) and other figures in this chapter (Figure 1.3.4 and Figure 1.3.5).

../../_images/LegendCLMToolDataFlow.jpeg

Figure 1.3.3 Legend for Data Flow Figures

Green arrows define the input to a program, while red arrows define the output. Cylinders define files that are either created by a program or used as input for a program. Boxes are programs.

You start with a description of a SCRIP grid file for your output grid file and then create mapping files from the raw datasets to it. Once, the mapping files are created mksurfdata_map is run to create the surface dataset to run the model.

1.3.5.1. Creating a Complete Set of Files for Input to CLM

  1. Create SCRIP grid datasets (if NOT already done)

    First you need to create a descriptor file for your grid, that includes the locations of cell centers and cell corners. There is also a “mask” field, but in this case the mask is set to one everywhere (i.e. all of the masks for the output model grid are “nomask”). An example SCRIP grid file is: $CSMDATA/lnd/clm2/mappingdata/grids/SCRIPgrid_10x15_nomask_c110308.nc. The mkmapgrids and mkscripgrid.ncl NCL script in the $CTSMROOT/tools/mkmapgrids directory can help you with this. SCRIP grid files for all the standard CLM grids are already created for you. See the Section called Creating an output SCRIP grid file at a resolution to run the model on for more information on this.

  2. Create domain dataset (if NOT already done)

    Next use gen_domain to create a domain file for use by DATM and CLM. This is required, unless a domain file was already created. See the Section called Creating a domain file for CLM and DATM for more information on this.

  3. Create mapping files for mksurfdata_map (if NOT already done)

    Create mapping files for mksurfdata_map with mkmapdata.sh in $CTSMROOT/tools/mkmapdata. See the Section called Creating mapping files that mksurfdata_map will use for more information on this.

  4. Create surface datasets

    Next use mksurfdata_map to create a surface dataset, using the mapping datasets created on the previous step as input. There is a version for either clm4_0 or CLM5.0 for this program. See the Section called Using mksurfdata_map to create surface datasets from grid datasets for more information on this.

  5. Enter the new datasets into the build-namelist XML database The last optional thing to do is to enter the new datasets into the build-namelist XML database. See Chapter 3 for more information on doing this. This is optional because the user may enter these files into their namelists manually. The advantage of entering them into the database is so that they automatically come up when you create new cases.

The $CTSMROOT/tools/README goes through the complete process for creating input files needed to run CLM. We repeat that file here:

$CTSMROOT/tools/README                                  Dec/05/2023

IMPORTANT NOTE: Normally tools for creating input datasets for CLM
such as surface dataset creation would be here. As well as post processing
or other utility side line tools. However, we are only supporting
tools for later versions of the code. The tools should all work to create
or process datasets from these versions.

Therefore if you need any tools here checkout:

ctsm5.1.dev158 or later and use it

Let us know if you run into issues here by posting to the CESM Forum
or sending email to ctsm-software@ucar.edu

   https://bb.cgd.ucar.edu/cesm/forums/ctsm-clm-mosart-rtm.134/

See this file for the latest information:

   https//docs.google.com/document/d/1FOluB3C7RTHu8vArWGjACwFjGJfxkLcaGP00l0585_k

  And the discussions/issues on github.com/CTSM regarding this