Running with a different analytical relaxation temperature profile and damping parameters e.g., the Polvani and Kushner (2002) setup

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 the default dry dynamical core set up to use the relaxation temperature profile and damping parameters of the Polvani and Kushner (2002) (PK02) set-up. The source code modifications are 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 in $CASEDIR. A tarred directory containing the required source code modiciations, 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 then translate these modifications into the approprirate file versions within their own CESM version. This can easily be achieved by differencing filename and filename-ORIG e.g., using xxdiff

xxdiff filename filename-ORIG 

The equivalent location for these modifications can then be identified within the CESM release 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: Add namelist parameters to control the use of the PK02 relaxation temperature profile

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:

pkstrat: type=logical. This controls whether the PK02 setup is used or whether the default Held-Suarez configuration is used. pkstrat=.True. for using the PK02 setup.

vgamma: type=real*8. This is the vortex γ parameter in K/km from PK02. This controls the polar stratospheric temperatures and, therefore, the strength of the stratospheric polar vortex.

These namelist parameters have been defined to be part of the group "pkstrat_nl" so these must be specified in $CASEDIR/user_nl_cam in the following format

&pkstrat_nl
  pkstrat=.True.
  vgamma=2.
/

The above will result in the PK02 relaxation temperature profile being used, with γ=2.

Step 3: Source code modifications to read in namelist parameters

The module $MODDIR/SourceMods/src.cam/held_suarez_cam.F90 contains a new subroutine called pkstrat_readnl and additional modifications that are required to read in the namelist parameters from user_nl_cam as defined above.

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 4: Source code modifications to add in the PK02 relaxation temperature and upper level sponge layer

The PK02 relaxation temperature profile and upper level sponge layer have been included in held_suarez.F90. Compare held_suarez.F90 and held_suarez.F90-ORIG. In addition to this, the call to held_suarez_1994 within held_suarez_cam.F90 has been modified to pass in the pkstrat and vgamma parameters. Compare held_suarez_cam.F90 and held_suarez_cam.F90-ORIG.

Step 5: Use a well resolved stratosphere.

It only really makes sense to use this configuration with a sufficiently well resolved stratosphere and a sufficiently high model lid. Here is an example of how to change the vertical resolution to that used in PK02 (see also the page on changing the vertical resolution).

PK02 use 40 sigma levels in the vertical with level interfaces defined in the Appendix of PK02 and mid-levels defined using the Simmons and Burridge (1981) scheme.

This NCL code can be used to create an initial condition file with a different number of vertical levels. The hybrid coefficients of the level interfaces for the PK02 levels are provided for the case of nlev=40 although they are currently commented out with the even sigma levels being the default. If you with to use the PK02 levels, uncomment the values of hyai and hybi for nlev=40 within levels.ncl. Set nlev=40 in makeic.ncl and set sandb=True (this will result in the mid-levels being defined using the Simmons and Burridge scheme). The number of levels must also be set for CESM, which for the case of 40 levels can be done with the following xmlchange command:

xmlchange --file env_build.xml --id CAM_CONFIG_OPTS --val "--phys held_suarez --nlev=40" 

Point toward the initial condition file that contains the required vertical levels. This can be done by setting the namelist parameter ncdata in user_nl_cam e.g.,

ncdata='myfilepath'  

where myfilepath points toward the new initial condition file.

Step 6: Modify the default diffusion parameters

By default, a fourth order hyperdiffusion with a damping timescale of 0.5 days on the smallest scale is used. The namelist parameters eul_hdif_order and eul_hdif_coef can be changed to use the values specified in PK02. See the section on "About the default configuration" here.

Step 7: Set-up, build and run the case

See steps 3 and 4 here.

Possible issues

Depending on the value of γ used, CFL violations may arise with the default timestep. If this occurs the timestep can be adjusted by setting the value of ATM_NCPL. The atmospheric timestep (in seconds) is given by 86400/ATM_NCPL. For example, running the following xmlchange command from within $CASEDIR will set the timestep to 600s.

./xmlchange ATM_NCPL=144