Read in a relaxation temperature profile
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 (a) control the dry dynamical core relaxation temperature profile via the namelist and (b) read in a user defined relaxation temperature profile (Tref) from a netcdf file using the Eulerian spectral-transform dynamical core. 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 versions 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
The equivalent location for these modifications can then be identified within the CESM distribution 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 the user defined Tref netcdf file in the required format
An NCL scripts that creates a netcdf file in the correct format for input to CESM can be found in
$MODDIR/NCL/make_tref_input.ncl
This can be modified to read in and interpolate an arbitrary relaxation temperature profile and write it to file
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 Tref
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:
treffromfile: type=logical. This controls whether or not Tref is to be read in from a user specified file. If treffromfile=.False. then use the default H-S relaxation temperature profile. If treffromfile=.True. then read in Tref from file.
treffile: type=char. This is the path to the location of the file containing the user specified relaxation temperature profile. This will be used when treffromfile=.True..
These namelist parameters have been defined to be part of the group "trefread_nl" so these must be specified in $CASEDIR/user_nl_cam in the following format
&trefread_nl treffromfile=.True. treffile='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 trefread_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.
The module $MODDIR/SourceMods/src.cam/runtime_opts.F90 also contains modifications to call trefread_readnl. Compare runtime_opts.F90 and runtime_opts.F90-ORIG.
Step 5: Source code modifications to enable reading in of a Tref profile
An additional subroutine named update_tref_eul has also beed added to held_suarez_cam.F90. This subroutine is responsible for reading in the three-dimensional relaxation temperature profile array from file. This is called from within the subroutine held_suarez_init and results in an array tref that contains the user specified relaxation temperature profile from file.
Step 6: Source code modification to use this Tref profile
The call to held_suarez_1994 within held_suarez_cam.F90 has been modified to include an additional optional argument treflchnk which contains the Tref 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 as the relaxation temperature profile if treffromfile=.True..