Download and Build

Defining your workspace

The first step is to create an environment variable that contains the path to the directory in which you will build and run the SCM. 

Go to the directory in which you will build and run the SCM and run the command below substituting /path/to/my/build/and/run/directory with your actual directory name

cd /path/to/my/build/and/run/directory

Next, define an environment variable that contains the path

For bash (Bourne Shell), k:

export SCM_WORK=`pwd`
 

For C-Shell:

setenv SCM_WORK `pwd`

Download the Tutorial Files

Files that are used throughout the exercises in this tutorial are available to download. Down load these to the $SCM_WORK directory.

Determining how you will use the SCM 

There are two supported ways to build and run the Single Column Model: the standard build, and with a Docker container. Please follow one of the options below for information on these two methods:

Review the physics suites

You will run two experiments with the SCM, showing the differences between all supported physics suites for a given case based on the Tropical Warm Pool – International Cloud Experiment (TWP-ICE) field campaign. Let’s first take a look at the composition of the physics suites and then at how the case is set up.

Navigate to the directory where the Suite Definition Files (SDFs) are stored and see what is available:

Peruse the files and notice the XML format, paying attention to the key elements: suite (with name attribute), group, subcycle, scheme.

You will find primary and interstitial schemes.  All suites share many common elements, including interstitial schemes that are required to prepare data for schemes and calculate diagnostics. 

As an example, the differences between the GFS_v16 suite (an approximation of the physics used for the GFS version 16 release) and the WoFS_v0 suite (a prototype for the operational implementation of NOAA's Warn-on-Forecast System) is shown below.

Q: What are some parameterizations used in suite WoFS_v0 that are not used in suite GFS_v16?

A: Coupling of subgridscale cloudiness and RRTMG radiation scheme (sgscloud_radpre and sgscloud_radpost), the Mellow-Yamada-Nakanishi-Niino (MYNN) surface layer (mynnsfc_wrapper) and planetary boundary layer (mynnedmf_wrapper) schemes. Also note that the GFS_v16 invokes a deep convective parameterization (samfdeepcnv), while suite WoFS_v0 does not. For this reason, suite WoFS_v0 is best suited for convective-allowing models.

Review the case configuration namelists and case input data file

Now navigate to the directory where case setup namelists are stored to see what you are going to run.

Look at twpice.nml to see what kinds of information are required to set up an experiment.

Each case also has a NetCDF file in DEPHY format associated with it (determined by the case_name variable) that contains the initial conditions and forcing data for the case. Take a look at one of the files to see what kind of information is expected:

There are scalar variables (single values relevant for the simulation), initial condition variables (function of vertical level only), and forcing variables (function of time and/or vertical level). Note that not all forcing variables are required to be non-zero. Additionally, there are global attributes which define the forcing type for the case.

Run the SCM

Now that you have an idea of what the physics suites contain and how to set up cases, you can run the SCM. 

The following commands will get you in the bin directory and run the SCM for the TWP-ICE case using all six supported suites.

Note: if you are using a Docker container, add -d at the end of the following command

Upon a successful run, the screen output should say that the runs completed successfully and the following subdirectories will be created in $SCM_WORK/ccpp-scm/scm/run/, each of them with a log file and results in NetCDF format in file output.nc: 

output_twpice_SCM_GFS_v16, output_twpice_SCM_GFS_v16_RRTMGP, output_twpice_SCM_GFS_v17_p8_ugwpv1, output_twpice_SCM_HRRR_gf, and output_twpice_SCM_WoFS_v0

Any standard NetCDF file viewing or analysis tools may be used to examine the output file (ncdump, ncview, Python, etc). 

Analyze the SCM results

The output directory for each case is controlled by its case configuration namelist. For this exercise, a directory containing the output for each integration is placed in the $SCM_WORK/ccpp-scm/scm/run/ directory. Inspect that the output directories now contain a populated output.nc file.

At this point, you use whatever plotting tools you wish to examine the output. For this course, we will use the basic Python scripts that are included in the repository. The main script is called scm_analysis.py and expects a configuration file as an argument. The configuration file specifies which output files to read, which variables to plot, and how to do so.

Set up the python environment needed to run the analysis script. First create the environment using a YAML file (only once) and activate the environment using conda.

Change into the following directory:

Copy Python plotting module needed for tutorial:

Run the following to generate plots for the TWP-ICE case:

Note: if you are using a Docker container, add -d at the end of the following command

You will notice some harmless messages pertaining to “Missing variables”, which are just meant to alert the user that some suites do not have certain types of parameterizations. Therefore, tendencies for those types of parameterizations are set to zero.

The script creates a new subdirectory within the 

$SCM_WORK/ccpp-scm/scm/run/ directory called plots_twpice_all_suites 

Change into that directory using the command

For docker, this directory is /home/plots_twpice_all_suites/comp/active. This is also mounted outside of the container, so you can exit the container and view the output files on your home file system in the directory $OUT_DIR/plots_twpice_all_suites/comp/active.

This directory contains various plot files in PDF format. Open the files and inspect the various plots such as the precipitation time series and the mean profiles of water vapor specific humidity, cloud water mixing ratio, temperature, and temperature tendencies due to forcing and physics processes.

Q: Examine the prediction of precipitation in file time_series_tprcp_rate_accum.pdf. Would you say that the rain rate is well predicted in the SCM simulations?

A: All supported suites reasonably predict the evolution of rain rate as a function of time and the results for all suites are similar, indicating that, for this variable, the commonality of forcing is a stronger factor in determining the results than the differences among suites. However, it should be noted that none of the suites capture the magnitude of the largest four precipitation events.

Q: Examine the profiles of temperature bias in file profiles_bias_T.pdf. In the lower troposphere (between the surface and 600 hPa), which suite(s) have a positive bias and which have a negative bias? In absolute terms, which suite has the highest bias in the lower troposphere?

A: In the lower atmosphere, suite WoFS_v0 have a positive bias (that is, it is too warm compared to observations), while all other suites have a negative bias (that is, are too cold compared to observations). In the middle atmosphere, all suites have a negative temperature bias. Suite WoFS_v0 has the largest absolute bias, which reaches -5 K.

Q: Look at the tendencies due to deep and shallow convection in file profiles_mean_multi_conv_tendencies.pdf. Considering all suites, at approximately which level do the deep convective tendencies peak? And the shallow convection tendencies? Why are the convective tendencies for suite WoFS_v0 zero?

A: The deep convective scheme represents cumulus clouds that span the entire troposphere and their tendencies peak at approximately 500 hPa. The shallow convective scheme represents clouds at the top of the planetary boundary layer, with maximum tendencies at approximately 950 hPa .Suite WoFs_v0 does not produce any convective tendencies since it does not include a convective scheme because it is targeted for convective-allowing resolutions.

Q: Since it does not include a convective parameterization, is it appropriate to use suite WoFS_v0 for the SCM TWP-ICE case?

A: No, suite WoFS_v0 is included with the SCM as-is for research purposes but it is not expected to produce reasonable results for the TWP-ICE case or other CCPP SCM cases involving deep convection. This is because forcing for existing cases assumes a horizontal scale for which deep convection is subgrid-scale and is expected to be parameterized. The WoFS_v0 suite was designed for use in simulations with horizontal scale small enough not to need a deep convection parameterization active, and it does not contain a deep convective scheme. For suite WoFS_v0 to produce reasonable results with the SCM, the forcing would have to be modified to account for deep convection.

Create a new CCPP suite, re-run the SCM, and inspect the output

In this exercise you will learn how to create a new suite and use it with the SCM. A new suite can have many different levels of sophistication. Here we will explore the simplest case, which is to add an existing CCPP physics scheme to an existing suite. In particular, we will create a modified version of the WoFS_v0 suite that contains a convective parameterization, in this case the Simplified Arakawa Schubert (SAS) scheme. One might find it useful to employ a convective parameterization (CP) when the model grid is too coarse to explicitly allow convection and when using a SCM with a forcing dataset that represents an average over a large area (such as the datasets distributed with CCPP v7.0.0). 

Note that no effort has been made to optimize the inter-parameterization communication in this new suite (for example, how microphysics and convection exchange information). This new suite is offered as a technical exercise only and its results should be interpreted with caution. If you want to learn more about creating suites, read the chapter on constructing suites in the CCPP Technical Documentation as it describes how Suite Definition Files (SDFs) are constructed.

This exercise has four steps:

• Create a New Suite Definition File for Suite SCM_WoFS_v0_sas 
• Prepare the Namelist File for the New Suite
• Rebuild the SCM
• Run the SCM and Inspect the Output

Step 1: Create a New Suite Definition File for suite SCM_WoFS_v0_sas

You will create a new SDF based on the SCM_WoFS_v0, but with the scale-aware SAS cumulus scheme. Note that interstitial schemes must also be added.

Edit ccpp/suites/suite_SCM_WoFS_v0_sas.xml and 

• Change the suite name to “SCM_WoFS_v0_sas”
• Add the scale-aware SAS deep and shallow cumulus schemes, the associated scheme/generic interstitial schemes, and the convective cloud cover diagnostic scheme to the “physics” group. The schemes you need to add are listed in bold below. You can also copy the new SDF instead of creating your own.
• Please note that the order of schemes within groups of a suite definition file is the order in which they will be executed. In this case, the placement of the schemes follows the placement of convective schemes from other GFS-based suites. In particular, deep convection precedes shallow convection and both need to appear in the time-split section of the “slow physics” part of the suite and before the microphysics scheme is called. Decisions about the order of schemes in general are guided by many factors related to physics-dynamics coupling, including numerical stability, and should be considered carefully. For example, one of the considerations should be to understand the “data flow” within a suite for each variable used within the added schemes, e.g. when/where the variables are modified in pre-existing schemes. This can be achieved by examining the variables’ Fortran “intents” in the pre-existing schemes’ metadata.

The suite name SCM_WoFS_v0_sas is listed below with the necessary additions highlighted in bold. 

Note: If you don’t want to type, you can copy a pre-generated SDF into place: 

The detailed explanation of each primary physics scheme can be found in the CCPP Scientific Documentation. A short explanation of each scheme is below:

Step 2: Prepare the Namelist File for the New Suite

We will use the default WoFS_v0 namelist input file to create the namelist file for the new suite:

Next, edit file input_WoFS_v0_sas.nml and modify the following namelist options to conform with the deep/shallow saSAS cumulus schemes in the SDF file :

shal_cnv   = .true.
do_deep    = .true.
imfdeepcnv = 2
imfshalcnv = 2

Check the Description of Physics Namelist Options for information.

Note: If you don’t want to type, you can copy a pre-generated namelist into place: 

Step 3: Rebuild the SCM

Now follow these commands to rebuild the SCM with the new suite included:

In addition to defining a SDF for a new suite, which only contains information about which schemes are used, one also needs to define parameters needed by the schemes in the suite (namelist file) as well as which tracers (tracer file) the SCM should carry that a given physics suite expects. There are two ways to provide this information at runtime. 

1. The first way is by giving command line arguments to the run script. For the namelist file, specify it with -n namelist_file.nml (assuming that the namelist file is in $SCM_WORK/ccpp-scm/ccpp/physics_namelists). For the tracer file, specify it with -t tracer_file.txt (assuming the tracer file is in $SCM_WORK/ccpp-scm/scm/etc/tracer_config).
2. The second way is to define default namelist and tracer configuration files associated with the new suite in the $SCM_WORK/ccpp-scm/scm/src/suite_info.py file, where a Python list is created containing default information for the SDFs.

If you are planning on using a new suite more than just for testing purposes, it makes sense to use the second method so that you don’t have to continually use the -n and -t command line arguments when using the new suite to run the SCM.

If you try to run the SCM using a new suite and don’t specify a namelist and a tracer configuration file using either method, the run script will generate a fatal error.

For the purpose of this tutorial, you will add new default values for the new suite to make your life easier, option 2. Edit $SCM_WORK/ccpp-scm/scm/src/suite_info.py to add default namelist and tracer files associated with two suites that we will create in this tutorial (the second suite has yet to be discussed, but let’s add it now for expediency):

Note: If you don’t want to type, you can copy pre-generated files into place:

Step 4: Run the Model and Inspect Output

Execute the following command to run the SCM for the TWP-ICE case using the new suite. Note that you don’t need to specify a tracer or namelist file since default ones now exist for this new suite.

Note: if you are using a Docker container, add -d at the end of the command

Upon completion of build, the following subdirectory will be created with a log file and results in NetCDF format in file output.nc: 

$SCM_WORK/ccpp-scm/scm/run/output_twpice_SCM_WoFS_v0_sas

In order to generate graphics, first prepare a configuration file for the plotting script using the commands below. 

Change into the following directory:

Edit plot_configs/twpice_scm_tutorial.ini. Since we only want to check how the scale-aware SAS scheme impacts the default WoFS_v0 suite, simply list the two suites in the first two lines of the file. Note that the second line defines the labels of the lines in the output plots and the third line defines the output directory for the plots.

Note: If you don’t want to type, you can copy over a pre-generated plot configuration file:

Change into the following directory:

Create the plots with the new suite with the command below.

Note: if you are using a Docker container, add -d at the end of the command

The script creates a new subdirectory within the $SCM_WORK/ccpp-scm/scm/run/ directory called plots_twpice_WoFSv0_sas/comp/active and places the graphics in there. Open the files and inspect the various plots for changes introduced by adding a convective parameterization.

Inspect the SCM Results

Q: Examine the prediction of precipitation in file time_series_tprcp_rate_accum.pdf. How does the new suite change the precipitation?

A: The time series of precipitation shows that WoFS_v0 with or without saSAS deep and shallow schemes produces similar results.

Q: Examine the profiles of temperature bias in file profiles_bias_T.pdf. How does adding a convective parameterization affect the vertical distribution of temperature bias?

A: It is interesting to see that, when a cumulus scheme is added, the positive temperature bias below 600 hPa is adjusted to -1 K and the negative bias around the 200 hPa is adjusted to -3.5 K, which is similar to the bias of other physics suites designed for applications in coarser grid spacing, as seen in the previous exercise.

Adding a New CCPP-Compliant Scheme

In this exercise you will learn how  to implement a new scheme in CCPP. This will be a simple case in which all variables that need to be passed to and from the physics are already defined in the host model and available for the physics. You will create a new CCPP-compliant scheme to modify the sensible and latent heat fluxes by adding a tunable amount to each of them. You will then implement the new scheme, which we will call fix_sys_bias_sfc, in the SCM_WoFS_v0 suite. Note that this procedure is provided only as an exercise to examine the impact of the surface fluxes on the prediction. While correcting the surface fluxes can help fix systematic biases,  there is no scientific basis for arbitrarily modifying the fluxes in this case.

This exercise has four steps:

• Prepare a CCPP-compliant scheme 
• Add the scheme to the Cmake list of files
• Add the scheme to the Suite Definition File
• Run the model and inspect the output

Step 1: Prepare a CCPP-compliant Scheme

The first step is to prepare a new CCPP-compliant scheme, which in this case will be called fix_sys_bias_sfc and will be responsible for “tuning” the surface fluxes. A skeleton CCPP-compliant scheme is provided for you to download into your codebase and continue developing. Two skeleton files fix_sys_bias_sfc.F90 and fix_sys_bias_sfc.meta, which are the scheme itself and the metadata file with the description of the variables passed to and from the scheme, respectively, need to be copied from tutorial_files/ directory and into the CCPP physics source code directory:

In the file fix_sys_bias_sfc.F90, you will need to add the following modifications to the subroutine  fix_sys_bias_sfc_run:

• Add hflx_r and qflx_r which correspond to the sensible and latent heat flux, respectively,  to the argument list in subroutine fix_sys_bias_sfc_run with 

subroutine fix_sys_bias_sfc_run (im, con_cp, con_rd, con_hvap, p1, t1, hflx_r, qflx_r, errmsg, errflg)

• Declare and allocate variables hflx_r and qflx_r

• Add code to modify the surface fluxes by adding a tunable amount of each of them or, in case of negative fluxes, setting the fluxes to zero. Note that the modification factors are converted to kinematic units since the variables hflx_r and qflx_r are in kinematic units, not W m2.

Where con_rd (287.05 J kg-1 K-1; ideal gas constant for dry air), con_cp (1004.6 J kg-1 K-1; specific heat of dry air at constant pressure), and con_hvap (2.5106 J kg-1; latent heat of evaporation and sublimation) are constants defined in the host model ($SCM_WORK/ccpp-scm/scm/src/scm_physical_constants.F90), and  sens_mod_factor and lat_mod_factor are arbitrary constants defined locally:

Given the value of the constants, this results in an increase of 40 W m-2 to the surface latent heat flux, while the sensible heat flux is not altered.                                                                                                            

After saving your changes, edit the corresponding metadata file: fix_sys_bias_sfc.meta to add variables hflx_r and qflx_r after the entry for variable t1. The order of the variables on the table should match the order of the arguments in the subroutine call.

The metadata file needs to be populated with the same variables as the subroutine fix_sys_bias_sfc_run call:

Note: If you don’t want to type, you can copy over completed versions of these files:

Step 2: Add the Scheme To the Cmake List of Files

Now that the CCPP-compliant scheme fix_sys_bias_sfc.F90 and the accompanying fix_sys_bias_sfc.meta are complete, it is the time to add the scheme to the CCPP prebuild configuration. 

Edit file $SCM_WORK/ccpp-scm/ccpp/config/ccpp_prebuild_config.py and include scheme fix_sys_bias_sfc.F90 in the SCHEME_FILES section:

Note: If you don’t want to type, you can copy over completed version:

Step 3: Add the Scheme To the Suite Definition File

The next step is to create a new Suite Definition File (SDF) and edit it so that it lists the scheme fix_sys_bias_sfc just after the GFS_surface_generic_post interstitial scheme:

First, create a new SDF from an existing SDF.

Next, the new SDF, suite_SCM_WoFS_v0_sas_sfcmod.xml, needs the following modifications:

• Change the suite name to “SCM_WoFS_v0_sas_sfcmod”
• Add the scheme “fix_sys_bias_sfc” after GFS_surface_generic_post

Note: If you don’t want to type, you can copy the completed SDF and modified supported  suite_list:

Step 4: Run the Model and Inspect the Output

After creating the new SDF, follow these commands to rebuild the SCM executable:

The following two commands will run the SCM for the TWP-ICE case using the modified suite containing the fix_sys_bias_sfc scheme, respectively.

Note: if you are using a Docker container, add -d at the end of the command

Upon completion of the run, the following subdirectory will be created containing a log file and results in NetCDF format in file output.nc: 

$SCM_WORK/ccpp-scm/scm/run/output_twpice_SCM_WoFS_v0_sas_sfcmod

Now you will create plots to visualize the results. Edit $SCM_WORK/ccpp-scm/scm/etc/scripts/plot_configs/twpice_scm_tutorial.ini to define the results that will be displayed: the WoFS_v0_sas results (which use the saSAS scheme), and the new results obtained with the surface fluxes modification:

Note: If you don’t want to type, you can copy over a pre-generated plot configuration file:

Change into the following directory:

Create the plots for the new suite with the command below.

Note: if you are using a Docker container, add -d at the end of the command

The new plots are under: 

$SCM_WORK/ccpp-scm/scm/run/plots_twpice_sas_sfcmod/comp/active/

Inspect the SCM results

Q: Examine the time series of latent and sensible heat fluxes in files time_series_lhf.pdf and time_series_shf.pdf, respectively. Are the modified latent and sensible heat fluxes as expected?

A: Compared to WoFSv0_sas, the surface latent heat flux in WoFSv0_sas_sfcmod is increased as expected, and the surface sensible heat flux adjusts to a lower value for much of the simulation.

Q: Examine the vertical profile of convective tendencies in file profiles_mean_dT_dt_conv.pdf. How  does the increased latent heat flux affect the atmospheric convection?

The evaporation process associated with the increased surface latent heat flux makes more moisture available in the atmosphere, which triggers stronger convection.

A: This exercise shows us that if some properties of the surface energy budget system change in such a way that the surface latent heat flux goes up, the system will rebalance to compensate for this change. In this case, we note that the sensible heat flux was reduced for much of the forecast, even though we did not modify it directly. The sensible heat flux depends on the difference in temperature between the sea surface temperature and the air, the wind speed, and the surface heat exchange coefficient. Given that sea surface temperature changes very slowly, the changes in sensible heat flux can be attributed to lowering of the air temperature or increase in the wind speed. Those are non-linear effects deriving from the increase in latent heat flux.

Add a new variable to a CCPP-compliant scheme

Adding a New Variable

In this section, we will explore how to pass a new variable onto an existing scheme. The surface latent and sensible heat fluxes will be adjusted in scheme fix_sys_bias_sfc to be time-dependent using the existing variable solhr (time in hours after 00 UTC at the current timestep). The surface fluxes will now only be modified between the hours of 20:30 and 8:30 UTC, which correspond to the hours of 6:00 AM and 6:00 PM local time in Darwin, Australia, where this case is located. 

Step 1: Add Time Dependency to the fix_sys_bias_sfc_time Scheme

Edit file $SCM_WORK/ccpp-scm/ccpp/physics/physics/fix_sys_bias_sfc.F90 and add solhr to the argument list for subroutine fix_sys_bias_sfc_run:

Then declare solhr as a real variable:

Next, add the time-dependent surface flux modification using an if statement between the CCPP error message handling and the do loop:

A metadata entry should be added to the table for subroutine fix_sys_bias_sfc_run in file $SCM_WORK/ccpp-scm/ccpp/physics/physics/fix_sys_bias_sfc.meta.

Note: If you don’t want to type, you can copy over completed versions of these files:

Since solhr is an existing variable, you do not need to modify the host model. Additionally, no changes are needed in the SDF or in the prebuild script since you are simply modifying a scheme and not adding a new scheme. You can proceed to rebuilding the SCM.

Step 2: Build the Executable, Run the Model, and Inspect the Output

Issue these commands to rebuild the SCM executable:

In order to avoid overwriting the output produced in exercise “Add a new scheme”, first rename the output directory:

The following command will run the SCM for the TWP-ICE case using suite WoFS_v0_sas_sfcmod with scheme fix_sys_bias_sfc modified to use variable solhr:

Note: if you are using a Docker container, add -d at the end of the command

Upon completion of the run, the following subdirectory will be created, with a log file and results in NetCDF format in file output.nc:

$SCM_WORK/ccpp-scm/scm/run/output_twpice_SCM_WoFS_v0_sas_sfcmod

To visualize the results, edit file $SCM_WORK/ccpp-scm/scm/etc/scripts/plot_configs/twpice_scm_tutorial.ini and add the new test directory name and label name to the first two lines:

Note: If you don’t want to type, you can copy over a pre-generated plot configuration file:

Change into the following directory:

Next, run the following command to generate plots for the last three exercises in this tutorial.

Note: if you are using a Docker container, add -d at the end of the command

The script creates a new subdirectory within the $SCM_WORK/ccpp-scm/scm/run/ directory called plots_twpice_R_sas_sfcmod_time/comp/active

Inspect the Results

Q: Examine the surface latent heat flux and the surface sensible heat flux in files time_series_lhf.pdf and time_series_shf.pdf, respectively. How does the latent heat flux differ from the previous exercise?

A: Instead of adding 40 W m-2 to the latent heat flux throughout the simulation, the latent heat flux value was modified only between the hours of 6 AM and 6 PM local time to mimic the observed diurnal cycle feature.

Q: Examine the temperature bias and the specific humidity bias  in files profiles_bias_T.pdf and profiles_bias_qv.pdf, respectively. How are the temperature and moisture profiles affected by the surface latent heat flux  modification?

A: Even though we effectively added more energy to the atmosphere, the net effect in the T and q profiles are either neutral or show an increase in negative bias. This points out that physics suites have complicated non-linear interactions and that it is often possible to get unexpected results. This also points to the utility of studying physics in a SCM context, where one at least has a chance at understanding the mechanisms when only dealing with one column and are excluding interactions/feedbacks due the presence and advection from surrounding columns.