7. Physics modifications via the namelist¶
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.
7.1. Radiative Constituents¶
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.
7.1.1. Default rad_climate for cam4 physics¶
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.
7.1.2. Default rad_climate for cam5 physics¶
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.
7.2. Example - 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.
7.3. Example - Diagnostic radiative forcing¶
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 distinguished 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.
7.4. Example - 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’ /”
7.5. Example - 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.