Impose an additional temperature tendency (read in from a netcdf file)

Note, these instructions are only valid for the 2018 CESM2 release. If you wish to run the Held-Suarez configuration prior to the CESM2 release, please contact Isla Simpson [ islas@ucar.edu ]

The following describes how to modify CAM namelist parameters and source code to add an additional temperature tendency to the dry dynamical core (in addition to the Held-Suarez relaxation). This temperature tendency is read in from a netcdf file. This set-up is designed to work for CESM2, but users should be able to follow these same instructions with subsequent model releases, although the exact location required for code modifications may differ slightly.

These instructions assume that the CESM release is located in the directory $CESM and the case directory is located at $CASEDIR. A tarred directory containing all the required modifications along with the original version of each file can be downloaded here. This directory will be referred to as $MODDIR. The original files are denoted by filename-ORIG so that users can compare these with the new versions to identify the modifications that have to be made. Users should translate these modifications into the appropriate file versions within their own CESM version. This can easily be achieved by differencing filename and filename-ORIG to view the changes that have to be made e.g. using xxdiff:

xxdiff filename filename-ORIG

These changes can then be made at the equivalent location within the CESM version being used.

The following files will need to be modified:

$CESM/components/cam/bld/namelist_files/namelist_definition.xml
$CESM/components/cam/src/control/runtime_opts.F90
$CESM/components/cam/src/physics/simple/held_suarez.F90
$CESM/components/cam/src/physics/simple/held_suarez_cam.F90

For the CESM source code modifications i.e., the .F90 files, the best practise is to copy these files into the directory $CASEDIR/SourceMods/src.cam and make the modifications there. The namelist_definition.xml file will need to be modified at $CESM/components/cam/bld/namelist_files/namelist_definition.xml.

Step 1: Set up your dry dynamical core case

Start by following the instructions for setting up the default Held-Suarez case here.

Step 2: Create a netcdf file contining the user defined heating perturbation in the required format

An NCL script that can be used to create a netcdf file that contains a heating perturbation in the correct format for input to CESM can be found at

$MODDIR/NCL/make_qpert_input.ncl

This can be modified to read in a user defined temperature perturbation (in K/s) from a netcdf file and output it to a netcdf file of the correct format to be read by CESM. See $MODDIR/NCL/README.txt for more information.

Note that, in this example, the relaxation temperature profile is being defined on the model hybrid-sigma coordinates. If it is to be defined on pressure levels, extra steps would have to be taken to interpolate from convert from pressure to hybrid-sigma coordinates in-line.

Step 3: Add namelist parameters to control the reading of the heating perturbation

User defined CAM namelist parameters need to be defined in

$CESM/components/cam/bld/namelist_files/namelist_definition.xml

The file $MODDIR/namelist_definition/namelist_definition.xml can be seen to contain two additional namelist parameters compared to the original:

qpertfromfile: type=logical. This controls whether or not an additional heating perturbation is to be read in from a user specified file. If qpertfromfile=.False. then use the default H-S relaxation temperature profile. If qpertfromfile=.True. then use the default H-S relaxation plus an additional temperature tendency read from qpertfile.

qpertfile: type=char. This is the path to the location of the file containing the user specified temperature tendency. This will be used when qpertfromfile=.True..

Add these namelist parameters to $CESM/components/cam/bld/namelist_files/namelist_definition.xml. These namelist parameters have been defined to be part of the group "qpertread_nl" so these must be specified in $CASEDIR/user_nl_cam in the following format

&qpertread_nl
  qpertfromfile=.True.
  qpertfile='myfilename.nc'
/

Step 4: Source code modifications to read in namelist parameters

The module $MODDIR/SourceMods/src.cam/held_suarez_cam.F90 contains a new subroutine called qpertread_readnl and additional modifications that are required to read in the namelist parameters from user_nl_cam as defined above. Users who wish to add in additional namelist parameters for other reasons can adapt this to their needs. Compare held_suarez_cam.F90 and held_suarez_cam.F90-ORIG

The module $MODDIR/SourceMods/src.cam/runtime_opts.F90 also contains modifications to call qpertread_readnl. Compare runtime_opts.F90 and runtime_opts.F90-ORIG.

Step 5: Source code modifications to read in the additional heating perturbation and apply it

The call to held_suarez_1994 within held_suarez_cam.F90 has been modified to include an additional optional argument qpertlchnk which contains the heating perturbation from file for the current chunk. Finally, the subroutine held_suarez_1994 within the held_suarez.F90 module has to be modified to receive this optional argument and then use it in addition to the Held-Suarez relaxation. Compare held_suarez_cam.F90 and held_suarez_cam.F90-ORIG and compare held_suarez.F90 and held_suarez.F90-ORIG. An additional history field has been added "QPERT" which contains the additional temperature tendency in K/s. See the instructions here for including this additional field in your model output.

Community Earth System Model