prescribe Soil Moisture in the Community Land Model, version 4

Contents:

Introduction

prescribeSM_CESM_1.2.x allows to prescribe SOILLIQ and SOILICE in CLM 4.0 for CESM 1.2.x.

The code is originally by Ruth Lorenz (with the help of Dave Lawrence) and has been adapted for CLM 4.0 and CESM 1.2.

Features

  • Prescribe SOILLIQ (and SOILICE) (-> SM) in CLM 4.0
  • Several methods to prescribe SM
  • Prescribe SM globally or regionally
  • Prescribe daily mean or monthly mean SM (linear interpolation in between)
  • Conveniently define options via namelist

Usage

  1. Run a reference simulation with CESM/ CLM, output SOILLIQ and SOILICE daily data.
  2. Process the output, e.g. calculate a climatology.
  3. Convert the 4D output file to 3D, if necessary.
  4. Add the necessary files and compile CESM.
  5. Create the namelist file, deciding what method to use to prescribe SM.
  6. Run CESM with prescribed SM

Installation

Note

This guide only explains how to add the extended functionality to CLM and not how CESM can be installed.

Obtaining the Source Code

The source code must first be obtained from github: git clone https://github.com/IACETH/prescribeSM_cesm_1.2.x.git

Compilation

There is one additional source code file and a number of original CLM files were changed (see Source Files). The files need to go in to the SourceMods folder ($CASEROOT/SourceMods/src.clm/) before CESM is compiled.

Soil Moisture Data Set

This file defines the target values which are prescribed in CLM. It is a netCDF file and needs to have the variables SOILICE and SOILLIQ on it (even if you only prescribe SOILLIQ). The variables are not in the usual lat/ lon format (named 4D) but in an indexed format (named 3D). The data is obtained from a reference simulation of CLM. The file must have 365 (12) time steps on it to prescribe SM daily (monthly) data.

Obtain SM Data Set from CLM

CLM can directly output the needed 3D soil moisture fields. Assume you want to output daily 4D files in history tape 2 and daily 3D fields in history tape 3, you have to add the following lines to user_nl_clm:

# daily SM, lat, lon grid:
hist_fincl2 = 'SOILICE', 'SOILLIQ'
# daily SM, column form
hist_fincl3 = 'SOILLIQ','SOILICE'
hist_nhtfrq = 0, -24, -24
hist_mfilt = 1, 365, 365
# conversion to lat/ lon format?
hist_dov2xy = .true., .true., .false.

Convert 4D to 3D

If you only have the SM forcing file in 4D format it is possible to convert it to a 3D file. A small python script that shows how to do this is given in the repository: clm_col_to_xy_example.py.

It translates the lat/ lon information to index information. This requires one 3D file with the used set up (create it as in Obtain SM Data Set from CLM).

Regional Forcing

  • if you set SOILLIQ or SOILICE to -1 at a gridpoint/ level, SOILLIQ and SOILICE are calculated interactively at this point
  • this can be used to prescribe SM only regionally
  • or at certain depths only

Warning

to prescribe SM only at certain time days of the year will only work if you use (1) daily data and (2) set

Namelist

PrescribeSM has its own namelist that is called prescribe_SM_nl. This namelist must go in the run directory of CESM. The location of the run directory is defined in $CASEROOT/env_run.xml under the entry “RUNDIR”.

Note

an example namelist is given with the code

Namelist Options

pSMfile : string
path to the history file containing SOILLIQ and SOILICE. If one_file_per_day is .true., the string patterns %y, %m, and %d are expanded to the year, day, and month of the simulation.
one_file_per_day : bool
If .false. uses the pSMfile as is, and iterates through the timesteps (days or months). If .true. uses one file per day and uses its first timestep. Default = .true..
pSMtype : int
Defines how to prescribe SM, see Methods to Prescribe Soil Moisture.
monthly : bool
If .false. uses daily input. If .true. assumes monthly mean SM is provided.
interp_day : bool
If .false. uses the daily mean, if .true. linearly interpolates between daily mean. Applies only if daily input data is used (monthly = .false.).
levstart : int, optional
First level to prescribe SM, default = 1.
levstop : int, optional
Last level to prescribe SM, default = 10.
use_qdrai : bool, optional
Only for pSMtype 3. Whether subsurface runoff (qdrai) is also used for irrigation, default = .true..
reservoir_capacity, float, optional
Only for pSMtype 3. Size of the reservoir where water can be transfered in time, default = 0.

Warning

if you set monthly=.true. but have a daily SM input file it will still work (uses the first 12 days as the months)

Methods to Prescribe Soil Moisture

pSMtype = 1
Prescribe SOILLIQ and SOILICE at every time step (PRES_LIQ+ICE). Ignores gridcells/ levels where SOILLIQ or SOILICE is negative.
pSMtype = 2
Prescribe SOILLIQ if soil temperature is above freezing (PRES_LIQ). Prescribes SOILLIQ + SOILICE at every time step. Ignores gridcells/ levels where SOILLIQ is negative.
pSMtype = 3
Not tested, do not use. Prescribe SOILLIQ if soil temperature is above freezing (PRES_LIQ) and only if runoff (or potentially water in the reservoir is available). Does not remove water. Prescribes SOILLIQ + SOILICE at every time step.
pSMtype = 4
As pSMtype = 2 but does not remove water.

Additional Info

Source Files

The three changed source files are:

  • prescribeSoilMoistureMod.F90
  • clm_driver.F90
  • BalanceCheckMod.F90
prescribeSoilMoistureMod.F90

The main file for prescribing soil moisture. Contains the following routines:

  • prescribeSoilMoisture
  • initPrescribeSoilMoisture
  • interpSoilMoisture
  • readSoilMoisture
clm_driver.F90

The subroutine prescribeSoilMoisture is called from the main program of CLM.

BalanceCheckMod.F90

Prescribing soil moisture violates the water and energy balance. Therefore these two checks have to be turned off.

Glossary

4D

The usual file.

time x level x latitude x longitude

3D
time x level x index

Indices and tables