Chapter 5. Physics modifications via the namelist

Table of Contents

5.1. Radiative Constituents
5.1.1. Default rad_climate for cam4 physics
5.1.2. Default rad_climate for cam5 physics
5.1.3. Diagnostic radiative forcing

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.

5.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.

5.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.

5.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.

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.


5.1.3. 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 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.