Table of Contents
This chapter is comprised of sections that explore how to customize various aspects of CAM's run time configuration. General instructions for building namelists using the build-namelist utility were given in Section 2.1.6, “Building the Namelist”, and details of the build-namelist utility are in Appendix B, The build-namelist utility.
The atmospheric constituents which impact the calculation of radiative fluxes and heating rates are referred to as radiative constituents. A single CAM run may potentially contain multiple sources of any given constituent, for example, a prognostic version of ozone from a chemistry scheme and a prescribed version of ozone from a dataset. The radiative constituent module was designed to
provide an explicit specification of the gas and aerosol constituents that impact the radiation calculations, and
allow this specification to be modified via the namelist.
A detailed description of the radiative constituent module is found in the Reference Manual.
Putting the entire specification of the radiative constituents into the
namelist results in a certain amount of complexity which is hard to avoid.
This sections begins with a description of what's in the default
specifications for both the cam4
and cam5
physics packages. Following that are some
examples of how to modify the default namelist settings.
The cam4
physics package uses prescribed gases (except
for water vapor), and prescribed bulk aerosols. rad_climate
is the
namelist variable which holds the specification of radiatively active
constituents. The default value of rad_climate
generated by build-namelist is:
rad_climate = 'A:Q:H2O', 'N:O2:O2', 'N:CO2:CO2', 'N:ozone:O3', 'N:N2O:N2O', 'N:CH4:CH4', 'N:CFC11:CFC11', 'N:CFC12:CFC12', 'N:sulf:/CSMDATA/atm/cam/physprops/sulfate_camrt_c080918.nc', 'N:dust1:/CSMDATA/atm/cam/physprops/dust1_camrt_c080918.nc', 'N:dust2:/CSMDATA/atm/cam/physprops/dust2_camrt_c080918.nc', 'N:dust3:/CSMDATA/atm/cam/physprops/dust3_camrt_c080918.nc', 'N:dust4:/CSMDATA/atm/cam/physprops/dust4_camrt_c080918.nc', 'N:bcar1:/CSMDATA/atm/cam/physprops/bcpho_camrt_c080918.nc', 'N:bcar2:/CSMDATA/atm/cam/physprops/bcphi_camrt_c080918.nc', 'N:ocar1:/CSMDATA/atm/cam/physprops/ocpho_camrt_c080918.nc', 'N:ocar2:/CSMDATA/atm/cam/physprops/ocphi_camrt_c080918.nc', 'N:SSLTA:/CSMDATA/atm/cam/physprops/ssam_camrt_c080918.nc', 'N:SSLTC:/CSMDATA/atm/cam/physprops/sscm_camrt_c080918.nc'
The rad_climate
variable takes an array of string values. Each of the
strings has three fields separated by colons. In this example the
first field of each string is either an A
or an N
. An A
indicates the constituent is advected and an N
indicates the constituent
is not advected. Generally a non-advected constituent is one whose value
is prescribed from a dataset but that's not always the case. It's also
possible that a non-advected constituent is one that has been prognosed by
a chemistry scheme (e.g. the cloud borne species in the modal aerosol
models) or diagnosed from other prognostic species. The second field
in each string is a name that is used to identify the constituent in the
appropriate internal data structure (there are separate data structures for
the advected and the non-advected constituents). The third field is
either a name from the set of gas specie names recognized by the radiation
code, or it is an absolute pathname of a dataset that contains physical and
optical properties of an aerosol. This third field is how CAM
distinquishes the gas from the aerosol species.
The names used for the prescribed gas species except ozone in both the cam4
and cam5
physics packages, i.e., O2
, CO2
,
N2O
, CH4
, CFC11
, and
CFC12
, are hardcoded in the
module ghg_data
which is responsible for setting the values of these
species in the physics buffer.
The name for water vapor,
Q
, is hardcoded in a cnst_add
subroutine call made
from subroutine phys_register
. The name for
ozone, ozone
, is hardcoded in the prescribed_ozone
module which is responsible for reading ozone datasets and setting the
values for ozone
in the physics buffer.
The names used to identify the gas species which must be provided to the cam4
radiation code
are H2O
, O2
, CO2
, O3
,
N2O
, CH4
, CFC11
, and
CFC12
. These names are hardcoded in the module
radconstants
. There are no datasets associated with the gas specie names
because the optical properties of the gases are handled by the radiation
code directly.
The names used to identify the bulk aerosol species are hardcoded in the
build-namelist utility and are specified to the prescribed_aero
module by the
namelist variable prescribed_aero_specifier
as follows:
prescribed_aero_specifier = 'sulf:SO4', 'bcar1:CB1', 'bcar2:CB2', 'ocar1:OC1', 'ocar2:OC2', 'sslt1:SSLT01', 'sslt2:SSLT02', 'sslt3:SSLT03', 'sslt4:SSLT04', 'dust1:DST01', 'dust2:DST02', 'dust3:DST03', 'dust4:DST04'
The first name in each of these colon separated pairs is the one the
prescribed_aero
module adds to the physics buffer, while the second name
is the variable name in the dataset. The first names for all the species
except the sea salt bins (sslt1
,
..., sslt4
) are the ones that appear in the
rad_climate
specifier. Sea salt is treated specially by repartitioning
the total mass in the four bins into a coarse and an accumulation mode with
the names SSLTC
and SSLTA
respectively. The repartitioning is done by the sslt_rebin
module.
Each of the aerosol species has an associated file which contains physical and optical properties.
The cam5
physics package uses the same prescribed gases as the cam4
package, but uses prognostic modal aerosols from
the trop_mam3
chemistry package. The default value of
rad_climate
generated by build-namelist is:
rad_climate = 'A:Q:H2O', 'N:O2:O2', 'N:CO2:CO2', 'N:ozone:O3', 'N:N2O:N2O', 'N:CH4:CH4', 'N:CFC11:CFC11', 'N:CFC12:CFC12', 'M:mam3_mode1:/CSMDATA/atm/cam/physprops/mam3_mode1_rrtmg_c110318.nc', 'M:mam3_mode2:/CSMDATA/atm/cam/physprops/mam3_mode2_rrtmg_c110318.nc', 'M:mam3_mode3:/CSMDATA/atm/cam/physprops/mam3_mode3_rrtmg_c110318.nc'
The gas species mass mixing ratios come from the same constituents in
cam5
as they did in cam4
(but the
radiative treatment is different since the rrtmg
radiation package replaces camrt
). Hence the
rad_climate
strings for the gasses are the same as they
were in the cam4
physics example.
The aerosol constituents in this rad_climate
specification are all in the
form of modes. The first field is an M
rather than an A
or an N
to
indicate that the aerosol constituents are modes. Roughly, the
rad_climate
variable lists the aerosol constituents whose contributions
are added together to compute the total aerosol optical depth. In the case
of the bulk aerosols the optical depths due to the individual aerosol
species are summed to find the total aerosol optical depth. In the case of
the modal aerosol model it is the modes that are summed. Hence each mode
has an entry in the rad_climate
list, along with a file that contains
physical and optical properties of the mode as a whole. In the example
above there are three modes identified by the names
mam3_mode1
, mam3_mode2
, and
mam3_mode3
. These names are hardwired in the build-namelist
utility and are only used to connect each mode with more detailed
specification of the constituents that comprise it. That specification is
given by the namelist variable mode_defs
and looks as follows for the
default trop_mam3
chemistry scheme.
mode_defs = 'mam3_mode1:accum:=', 'A:num_a1:N:num_c1:num_mr:+', 'A:so4_a1:N:so4_c1:sulfate:/CSMDATA/atm/cam/physprops/sulfate_rrtmg_c080918.nc:+', 'A:pom_a1:N:pom_c1:p-organic:/CSMDATA/atm/cam/physprops/ocpho_rrtmg_c101112.nc:+', 'A:soa_a1:N:soa_c1:s-organic:/CSMDATA/atm/cam/physprops/ocphi_rrtmg_c100508.nc:+', 'A:bc_a1:N:bc_c1:black-c:/CSMDATA/atm/cam/physprops/bcpho_rrtmg_c100508.nc:+', 'A:dst_a1:N:dst_c1:dust:/CSMDATA/atm/cam/physprops/dust4_rrtmg_c090521.nc:+', 'A:ncl_a1:N:ncl_c1:seasalt:/CSMDATA/atm/cam/physprops/ssam_rrtmg_c100508.nc', 'mam3_mode2:aitken:=', 'A:num_a2:N:num_c2:num_mr:+', 'A:so4_a2:N:so4_c2:sulfate:/CSMDATA/atm/cam/physprops/sulfate_rrtmg_c080918.nc:+', 'A:soa_a2:N:soa_c2:s-organic:/CSMDATA/atm/cam/physprops/ocphi_rrtmg_c100508.nc:+', 'A:ncl_a2:N:ncl_c2:seasalt:/CSMDATA/atm/cam/physprops/ssam_rrtmg_c100508.nc', 'mam3_mode3:coarse:=', 'A:num_a3:N:num_c3:num_mr:+', 'A:dst_a3:N:dst_c3:dust:/CSMDATA/atm/cam/physprops/dust4_rrtmg_c090521.nc:+', 'A:ncl_a3:N:ncl_c3:seasalt:/CSMDATA/atm/cam/physprops/ssam_rrtmg_c100508.nc:+', 'A:so4_a3:N:so4_c3:sulfate:/CSMDATA/atm/cam/physprops/sulfate_rrtmg_c080918.nc'
Similarly to the rad_climate
variable, the mode_defs
variable is an
array of strings which provide a definition for all the modes that may be
used in a single run. The modes don't all need to appear in the
rad_climate
variable; some may only be needed for diagnostic radiation
calculations which will be discussed in more detail later.
There are three different types of strings in mode_defs
:
The initial string in each mode specification contains three fields. The first is a name that identifies the mode, the second is a name that identifies the type of the mode, and the final is the token "=".
One string in each mode specification must contain the names for the mode number concentrations in both the interstitial and cloud borne phases.
One or more strings in each mode specification must contain the names for the mass mixing ratios in both the interstitial and cloud borne phases of the individual constituents that comprise the mode.
The example of mode_defs
above has been formatted in a way that makes the
individual parts of each mode definition stand out. The actual output from
the build-namelist utility is not formatted like this and is a bit harder to
decipher.
What follows is an detailed explanation of the mode definitions in the example above.
There are three modes defined, i.e., mam3_mode1
,
mam3_mode2
, and mam3_mode3
. The name of a mode is arbitrary, the only
requirement being that the same name is used in the rad_climate
(or
rad_diag_N
) and the mode_defs
variables. These default mode names for
trop_mam3
are
hardcoded in the build-namelist utility. The three modes are of type accum
(accumulation), aitken
, and coarse
respectively. The names for the
mode types are hardcoded in the modal_aero_data
module.
The second line in the definition of each mode contains
the names of the number concentrations for the interstitial and cloud borne
phases. Looking specifically at the definition for mam3_mode1
, the first
two fields are for the interstitial phase and specify that the name
num_a1
is an advected constituent (A
), while the third and fourth
fields are for the cloud borne phase and specify that the name num_c1
is
a non-advected constituent (N
). The names of the number concentration
constituents are hardcoded in the modal_aero_initialize_data
module. The
fifth field, num_mr
, is a fixed token recognized by the
parser of the mode_defs
strings (in the rad_constituents
module) as an
indicator that the string contains the number concentration names. The
final token in the string, a "+", signals to the parser that the definition
of the current mode continues in the next string.
The third through final strings in each mode definition
contain specifications for each specie in the mode. Looking again at the
definition of mam3_mode1
, the first specie is of type sulfate
which is
indicated by the fifth field in that string. The specie type names are
hardcoded in the modal_aero_data
module. The first two fields in the
string provide the name for the mass mixing ratio of the specie in the
interstitial phase (so4_a1
), and indicate that it is an advected
constituent (A
). Fields three and four specify that the name of the mass
mixing ratio for the cloud borne phase is so4_c1
, and that this is a
non-advected constituent (N
). The names of the mass mixing ratio
constituents are hardcoded in the modal_aero_initialize_data
module. The
sixth field in the string is the absolute pathname of the file containing
physical and optical properties of the specie. The last field in the
string contains the token "+" which again indicates that the definition of
the mode continues in the next string.
Example 5.1. Modify a radiatively active gas
Suppose that we wish to modify the distribution of water vapor that is seen by the radiation calculations. More specifically, consider modifying just the stratospheric part of the water vapor distribution while leaving the troposheric distribution unchanged. To modify a radiatively active gas two things must be done.
Change the name (and possibly the type) of the constituent which is
providing the mass mixing ratios to the radiation code. This is a simple
modification to the rad_climate
value.
Make the necessary modifications to CAM to provide the new constituent
mixing ratios. A likely scenario for this example would be to create a new
module which is responsible for adding the modified water vapor field to
the physics buffer. This module could leverage the existing tropopause
module to determine the vertical levels where changes need to be made. It
could also leverage existing modules for reading and interpolating prescribed
constituents, for example the prescribed_ozone
module.
Details of how to make this type of source code modification won't be
covered here.
Now suppose the source code modifications have been made and the new water
vapor constituent is in the physics buffer with the name Q_fixstrat
. The
best way to modify the rad_climate
variable is to start from a value that
was generated by build-namelist for the configuration of interest but with the
default water vapor, and then to modify that version of rad_climate
and
add the modified version to the build-namelist command in our run script. Note
that the entire value of rad_climate
must be specified. There is no way
to just modify one individual string in the array of string values.
If we are running with a default cam5
configuration then the customized
namelist would be generated by the following command.
$camcfg/build-namelist ... \ -namelist "&cam ... rad_climate = 'N:Q_fixstrat:H2O', 'N:O2:O2', 'N:CO2:CO2', 'N:ozone:O3', 'N:N2O:N2O', 'N:CH4:CH4', 'N:CFC11:CFC11', 'N:CFC12:CFC12', 'M:mam3_mode1:/CSMDATA/atm/cam/physprops/mam3_mode1_rrtmg_c110318.nc', 'M:mam3_mode2:/CSMDATA/atm/cam/physprops/mam3_mode2_rrtmg_c110318.nc', 'M:mam3_mode3:/CSMDATA/atm/cam/physprops/mam3_mode3_rrtmg_c110318.nc' /"
The only difference between this version of rad_climate
and the default
is that the string for water vapor:
'A:Q:H2O'
has been replaced by
'N:Q_fixstrat:H2O'
In addition to specifying the new name for the constituent (Q_fixstrat
), it was
necessary to replace the A
by an N
since the new constituent is not
advected, even though it is derived in part for the constituent Q
which
is advected.
There are several namelist variables available for direct radiative forcing
calculations in the cam5
physics package. But note that these online
calculations are enabled for RRTMG only and not for the CAM_RT
radiation code used in the cam4
and earlier physics packages. The
ability to do radiative forcing calculations with CAM_RT is provided by
using the offline tool PORT which is documented
here, and
described in the paper Conley et al. [2013]. The PORT
functionality is included in the CESM release code.
Namelist variables are available for ten radiative forcing calculations;
rad_diag_1
, ..., rad_diag_10
. The values of these variables use the
exact same format as the rad_climate
variable. When a diagnostic
calculation is requested, for example by setting the variable rad_diag_1
,
then the default history output variables for the radiative heating rates
and fluxes will be output for the diagnostic calculation as well. The
names of the variables for the diagnostic calculation will be distinquished
from those that affect the climate simulation by appending the strings
'_d1
', ..., '_d10
' for diagnostic calculations specified by rad_diag_1
through rad_diag_10
respectively.
Example 5.2. Aerosol radiative forcing
To compute the total aerosol radiative forcing we need a diagnostic
calculation in which all the aerosols have been removed. To do this we
start from the default setting for the rad_climate
variable, use that as
the initial setting for rad_diag_1
, and then edit that initial setting to
remove the aerosols. In the cam5
physics this involves removing the
specification of the three modes, so we end up with a setting in our
build-namelist command that looks like this
$camcfg/build-namelist ... \ -namelist "&cam ... rad_diag_1 = 'A:Q:H2O', 'N:O2:O2', 'N:CO2:CO2', 'N:ozone:O3', 'N:N2O:N2O', 'N:CH4:CH4', 'N:CFC11:CFC11', 'N:CFC12:CFC12' /"
Example 5.3. Black carbon radiative forcing
To compute the radiative forcing of a single aerosol specie we need a diagnostic
calculation in which that specie has been removed from all modes that
contain it. This is a bit more complicated that the previous example where
we were able to remove entire modes from the value of rad_diag_1
.
Removing species from modes requires us to create new mode definitions.
Using black carbon as a specific example, we see from the default
definitions of the trop_mam3
modes
(Section 5.1.2, “Default rad_climate
for cam5
physics”) that black carbon is only
contained in mam3_mode1
. The best way to create the definition of a new
mode which doesn't contain black carbon is to copy the definition of
mam3_mode1
, change its name, and remove the black carbon from the
definition. Then use this new mode in place of mam3_mode1
in the
specifier for rad_diag_1
. Below is an outline of our build-namelist command
with just the mode_defs
and rad_diag_1
variables listed.
$camcfg/build-namelist ... \ -namelist "&cam ... mode_defs = 'mam3_mode1:accum:=', 'A:num_a1:N:num_c1:num_mr:+', 'A:so4_a1:N:so4_c1:sulfate:/CSMDATA/atm/cam/physprops/sulfate_rrtmg_c080918.nc:+', 'A:pom_a1:N:pom_c1:p-organic:/CSMDATA/atm/cam/physprops/ocpho_rrtmg_c101112.nc:+', 'A:soa_a1:N:soa_c1:s-organic:/CSMDATA/atm/cam/physprops/ocphi_rrtmg_c100508.nc:+', 'A:bc_a1:N:bc_c1:black-c:/CSMDATA/atm/cam/physprops/bcpho_rrtmg_c100508.nc:+', 'A:dst_a1:N:dst_c1:dust:/CSMDATA/atm/cam/physprops/dust4_rrtmg_c090521.nc:+', 'A:ncl_a1:N:ncl_c1:seasalt:/CSMDATA/atm/cam/physprops/ssam_rrtmg_c100508.nc', 'mam3_mode2:aitken:=', 'A:num_a2:N:num_c2:num_mr:+', 'A:so4_a2:N:so4_c2:sulfate:/CSMDATA/atm/cam/physprops/sulfate_rrtmg_c080918.nc:+', 'A:soa_a2:N:soa_c2:s-organic:/CSMDATA/atm/cam/physprops/ocphi_rrtmg_c100508.nc:+', 'A:ncl_a2:N:ncl_c2:seasalt:/CSMDATA/atm/cam/physprops/ssam_rrtmg_c100508.nc', 'mam3_mode3:coarse:=', 'A:num_a3:N:num_c3:num_mr:+', 'A:dst_a3:N:dst_c3:dust:/CSMDATA/atm/cam/physprops/dust4_rrtmg_c090521.nc:+', 'A:ncl_a3:N:ncl_c3:seasalt:/CSMDATA/atm/cam/physprops/ssam_rrtmg_c100508.nc:+', 'A:so4_a3:N:so4_c3:sulfate:/CSMDATA/atm/cam/physprops/sulfate_rrtmg_c080918.nc', 'mam3_mode1_noBC:accum:=', 'A:num_a1:N:num_c1:num_mr:+', 'A:so4_a1:N:so4_c1:sulfate:/CSMDATA/atm/cam/physprops/sulfate_rrtmg_c080918.nc:+', 'A:pom_a1:N:pom_c1:p-organic:/CSMDATA/atm/cam/physprops/ocpho_rrtmg_c101112.nc:+', 'A:soa_a1:N:soa_c1:s-organic:/CSMDATA/atm/cam/physprops/ocphi_rrtmg_c100508.nc:+', 'A:dst_a1:N:dst_c1:dust:/CSMDATA/atm/cam/physprops/dust4_rrtmg_c090521.nc:+', 'A:ncl_a1:N:ncl_c1:seasalt:/CSMDATA/atm/cam/physprops/ssam_rrtmg_c100508.nc' rad_diag_1 = 'A:Q:H2O', 'N:O2:O2', 'N:CO2:CO2', 'N:ozone:O3', 'N:N2O:N2O', 'N:CH4:CH4', 'N:CFC11:CFC11', 'N:CFC12:CFC12', 'M:mam3_mode1_noBC:/CSMDATA/atm/cam/physprops/mam3_mode1_rrtmg_c110318.nc', 'M:mam3_mode2:/CSMDATA/atm/cam/physprops/mam3_mode2_rrtmg_c110318.nc', 'M:mam3_mode3:/CSMDATA/atm/cam/physprops/mam3_mode3_rrtmg_c110318.nc' /"
Note that we just appended the new mode definition, mam3_mode1_noBC
, to
the end of the modes used in the climate calculation, and then used that
mode in place of mam3_mode1
in the rad_diag_1
value.