The fsurdat and mask mesh modifier tools for land surface modifications

These instructions apply to CTSM tags ctsm5.1.dev116 or later and CESM tags cesm2_3_beta12 or later.

The following describes how to modify land surface properties from the command line using tools that are contained within a CESM (or CTSM) release tag.  These tools are located in \$CESM/components/clm/tools/modify_input_files, where \$CESM refers to the location of the CESM tag.  Or, if you are using CTSM, the tools can be found in \$CTSM/tools/modify_input_files where \$CTSM refers to the location of the CTSM tag.  These tools can be run from the command line or, alternatively, they can be run interactively from the VisualCaseGen GUI.

The relevant files for modifying land surface properties are modify_fsurdat_template.cfg which contains inputs to the fsurdat modifier tool and fsurdat_modifier which is the fsurdat modifier tool.  Below the use of this tool is illustrated with some example experiments.

1. Introduction to mesh files

1.1 What are mesh files and how do they control the landmask?

Mesh files contain information that describes the model grid, such as grid centers and vertices as well as the area and mask for the cell and the connectivity of gridcells.  The mesh files that are being used are set by variables such as "MASK_MESH", "ATM_DOMAIN_MESH", "LND_DOMAIN_MESH" etc in the file env_run.xml in the case directory.  In practise, it is the "MASK_MESH" file that governs which grid points are land and which grid points are ocean and this contains 1's for ocean and 0's for land.  The land mask is then set as the inverse of this.  The primary purpose of the component mesh files "ATM_DOMAIN_MESH", "LND_DOMAIN_MESH" etc is to set the grids for each component as opposed to setting the landmask, so these files contain 1's everywhere.  As a result, if modifications to the landmask is necessary, this modification should be done in the file that is set by the "MASK_MESH" variable in env_run.xml. 

If your experiment is an uncoupled case, such as an offline-land case (I-case) or  prescribed SST simulation (F-case), the "mesh_mask_modifier" tool can be used to modify the landmask.  This only works for regular grids, such as the f09_f09 grid.  If you want to modify the land-mask in a coupled case that is using an irregular grid, then you'd instead need to use the MOM6 ocean bathymmetry tool to modify the mesh file (as in the third example below).

1.2 How do you find the default mesh file?

To modify the mesh file, you'll likely need to know what the default mesh file is for a case with real world geography and the resolution you wish to use.  To determine the default mesh file, you can set up a case using your desired compset and resolution e.g., suppose you want to use the compset FHIST and the resolution f09_f09, a case can be set up by

 cd $CESM/cime/scripts 
 ./create_newcase --case path_to_case --compset FHIST --res f09_f09_mg17

where "path_to_case" refers to the file path in which you'd like to place the case directory.  Now, go to that case directory and examine the file env_run.xml.

The variable "MASK_MESH" in env_run.xml points to the mesh file that governs the landmask.  However, for many of the supported grids this mesh file is for an irregular grid and if you are running without the ocean and using the CTSM mesh_mask_modifier tool then you'll need to use a mesh file for an irregular grid.  In the above example we find the following in env_run.xml

<entry id="LND_DOMAIN_MESH" value="$DIN_LOC_ROOT/share/meshes/fv0.9x1.25_141008_polemod_ESMFmesh.nc">
  <type>char</type>
  <desc>lnd mesh file (full pathname)</desc>
</entry>
<entry id="MASK_MESH" value="$DIN_LOC_ROOT/share/meshes/gx1v7_151008_ESMFmesh.nc">
   <type>char</type>
   <desc>mask mesh file (full pathname)</desc>
</entry>

The "gx1v7" in the MASK_MESH file indicates that this is an irregular grid.  Instead, we can use the regular grid of the LND_DOMAIN_MESH file to modify our landmask and use this as the MASK_MESH file instead of the default.  If, instead, you'd like to stick with the irregular grid for the mesh file, then the mesh file would have to be modified using the MOM6 bathymmetry tool, rather than the CTSM tool.

2. Introduction to the fsurdat file

2.1 What is the fsurdat file?

The fsurdat file controls the land surface properties and their time evolution (where relevant).  It is used to set features such as the properties of the soil (e.g., the percentage of sand versus clay, versus organic matter), the types of plants that are covering the grid cell (plant functional types, or PFTs),  the fraction of the grid cell that is covered by wetlands, lakes, glaciers or urban areas and the properties of these urban areas, the depth to the bedrock which affects the water holding capacity of the soil etc.  It does not, however, set the land fraction - that is set by the mesh file (see section 1).  CTSM/CLM is typically run in two primary modes (Satellite phenology, or BGC).  In Satellite phenology, properties of the vegetation such as leaf area index, stem area index, vegetation height etc are specified in the fsurdat file.  In BGC mode, these are emergent prognostic properties within the model.  If you want to alter the vegetation or soil properties on the real world continents (example 2 below) or you want to specify these properties on some new continental geometries that you have created, the fsurdat file is the place to do it.   

2.2 How do you find the default fsurdat file?

The default fsurdat file can be determined by setting up a case using the grid and compset that you want to use (see section 1.2 above).  Once you have set up your case, you can go into your case directory and preview the namelist.

cd path_to_case
./preview_namelists

The default namelist parameters for the land model can then be found in ./CaseDocs/lnd_in.  The namelist parameter "fsurdat" points to the default fsurdat file.  If you want to modify the land surface properties, it is this file that you'll want to change.

Another useful file in the land namelist is "paramfile".  This points toward a parameter file which contains the variables pftnum and pftname i.e., the number and name of each plant functional type.  This can be useful for determining which pft number you'd like to use for your modified land surface properties.

3. Finding the default landmask

While the mesh file (section 1) governs the landmask in the model, it is not in the most user friendly format to determine what the default landmask actually is.  You'll often want to know this if you're trying to modify the real-world continents.  If you are basing your new continental geometry on the original one that is used in default CESM (as in the fill Indian Ocean example in Example 1 below, then you'll need a file that contains the original land mask.  This can be achieved by first running a short simulation with the default configuration.  Ensure you obtain history files for the land model e.g., if you are only running a simulation for a few days, make sure to output daily frequency variables for the land file.  Not matter what variables you output from the land model, the land model history files contain a variable "landmask" that has values of 0 for ocean and 1 for land.

4. How to use these tools.

The following three examples illustrate how to use these tools in three different contexts:

  • Example 1: Fill Indian Ocean.  An uncoupled case where the starting point is the real world continental geometry but the landmask is being modified, and idealized properties are being specified for the new land surface area.
  • !! coming soon !! Example 2: Idealized land use change over North America.  An uncoupled case where the continents are not changed, but the land surface properties on real-world continents are modified.
  • !! coming soon !! Example 3: Ridge world.  A coupled aquaplanet with a since strip of land.  An coupled example with idealized bathymmetry, continental geometry, and land surface properties.