1.3.1. What are the CLM tools

There are tools provided with CLM that allow you, for example, to create your own input datasets at resolutions you choose or to compare CLM history files between different cases. Tools are available in the $CTSMROOT/tools directory. Some tools are FORTRAN stand-alone programs in their own directory. There is a suite of NCL scripts in the $CTSMROOT/tools/unsupported directory. Some of the tools also call the ESMF regridding program.

The tools produce files that can be used with CTSM1. If you need files for earlier versions of the model, you will likely need to use the tools present in the earlier versions.

The list of scripts and programs in $CTSMROOT/tools is as follows:

  1. mksurfdata_esmf to create surface datasets from gridded datasets that we refer to as raw datasets (ctsm5_2 and newer versions).

  2. crop_calendars to regrid and process GGCMI sowing and harvest date files for use in CTSM

  3. site_and_regional contains scripts to handle input datasets for site and regional cases; these scripts help with creation of datasets using the standard process, or subsetting existing datasets, and also overwriting aspects for specific cases

  4. modify_input_files contains scripts to modify CTSM input files, in particular surface datasets and mesh files

  5. unsupported contains miscellaneous useful unsupported tools contributed by users; these tools may or may not work

  6. cprnc to compare two NetCDF files. This is not in $CIMEROOT/tools and information is available in section 1.3.7.

Subsequent sections provide details about these tools, while the following $CTSMROOT/tools/README.md goes through the complete process for creating input files needed to run the CLM:

# CTSM Tools for Preprocessing of Input Datasets or Postprocessing of History Output
#### $CTSMROOT/tools/README.md

CTSM tools for analysis of CTSM history files -- or for creation or
modification of CTSM input files.

I. General directory structure NOW IN THE USER'S GUIDE

II. Notes on building and running the tools:

    mksurfdata_esmf has a cime configure and CMake based build using the following files:

        gen_mksurfdata_build ---- Build mksurfdata_esmf
        src/CMakeLists.txt ------ Tells CMake how to build the source code
        Makefile ---------------- GNU makefile to link the program together
        cmake ------------------- CMake macros for finding libraries

    Tools with copies of files from other directories include a README.filecopies.md for more information.

    Tools may have files with the directory name followed by .namelist to provide sample namelists, such as

        <directory>.namelist ---- Namelist to create a global file

    These files are also used by the test scripts to test the tools (see the
    README.testing.md) file.

> [!NOTE]
> Be sure to change the path of the datasets referenced by these namelists to
> point to where you have exported your CESM inputdata datasets.

III. Process sequence to create input datasets needed to run CTSM

    1. Create ESMF MESH grid files (if needed)

       a. For standard resolutions these files will already be created. (done)

       b. Run `tools/site_and_regional/subset_data point` to create single-point datasets

       This creates just the fsurdat file as MESH files are NOT needed for single-point cases.

       c. Run `tools/site_and_regional/subset_data region` to create regional datasets subset from a global dataset

       This creates both the fsurdat file and MESH file needed to run.

       d. General custom grid

        You'll need to convert or create MESH grid files on your own (using scripts
        or other tools) for the general case where you have an unstructured grid, or
        a grid that is not regular in latitude and longitude, and that grid is custom
        and not merely subset from one of the global grids.

    2. Create surface datasets with mksurfdata_esmf on Derecho
        (See mksurfdata_esmf/README.md for more help on doing this)

       - gen_mksurfdata_build to build
       - gen_mksurfdata_namelist to build the namelist
       - gen_mksurfdata_jobscript_single to build a batch script to run on Derecho
       - Submit the batch script just created above

       - This step uses the results of step (1) entered into the XML database.
       - If datasets were NOT entered into the XML database, set the resolution
         by entering the mesh file using the options: --model-mesh --model-mesh-nx --model-mesh-ny

       Example: for 0.9x1.25 resolution for 1850

``` shell
       # On Derecho
       cd mksurfdata_esmf
       ./gen_mksurfdata_build
       ./gen_mksurfdata_namelist --res 0.9x1.25 --start-year 1850 --end-year 1850
       ./gen_mksurfdata_jobscript_single --number-of-nodes 2 --tasks-per-node 128 --namelist-file target.namelist
       qsub mksurfdata_jobscript_single.sh
```

    3. Add new files to XML data or using user_nl_clm (optional)

       See notes on doing this in step (1) above.

IV.  Notes on which input datasets are needed for CTSM

       global or regional grids
         - need fsurdata
         - need mesh files in env_run.xml ATM_DOMAIN_MESH and LND_DOMAIN_MESH

       single-point grids
        - Just need fsurdata

The $CTSMROOT/tools/unsupported/README.md covers what you need to know about the unsupported tools:

# CTSM Unsupported Tools
#### $CTSMROOT/tools/unsupported/README.md

## History

Updated 2026/08/11 slevis

Written 2019/01/24 ekluzek

## Purpose
This directory is for CTSM users to contribute scripts that others may find
useful. Contributors should always add documentation within their scripts. We
consider these scripts unsupported, and they may or may not work. Also settings
within the scripts may be hardwired, e.g. paths may assume NCAR's directory
structures.

## Basic instructions
Python scripts require the following settings before running on NCAR's
supercomputers. The `py_env_create` step is required once, unless one needs to
update their `ctsm_pylib` environment:

``` shell
module load conda
../../py_env_create
conda activate ctsm_pylib
```

ncl scripts work as follows on NCAR's supercomputers:
``` shell
module load ncl
ncl script_name.ncl
```

## Note
The separate repository `https://github.com/NCAR/CMIP7_inputdata_processing`
includes contributions from the LMWG, each with README instructions.