CCPP and SCM Online Tutorial | Exercise 3: Add a new CCPP-compliant scheme

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.