FAQ: How do I add a new variable to a scheme?

How do I add a new variable to a scheme?

An answer to this question may be found in the instructional video available at https://youtu.be/58vpLYRpWhw. A summary of the procedure is outlined below.

First of all, you should identify the new variable and check if it is already available for use in the CCPP by consulting the metadata information in GFS_typedefs.meta or by perusing file ccpp/framework/doc/DevelopersGuide/CCPP_VARIABLES_{FV3,SCM}.pdf generated by ccpp_prebuild.py.

• If the variable is already available, it can be invoked in the scheme’s metadata file and one can skip the rest of this subsection.
• If the variable required is not available, consider if it can be calculated from the existing variables in the CCPP. If so, an interstitial scheme can be created to calculate the variable. However, the variable must be defined but not initialized in the host model as the memory for this variable must be allocated on the host model side. Instructions for how to add variables to the host model are available in the  CCPP Technical Documentation.
• If the variable is not available and can not be calculated from the existing variables in the CCPP, it means that a new variable needs to be defined. It is important to note that not all data types are persistent in memory. Most variables in the interstitial data type are reset (to zero or other initial values) at the beginning of a physics group and do not persist from one set to another or from one group to another. The diagnostic data type is periodically reset because it is used to accumulate variables for given time intervals. However, there is a small subset of interstitial variables that are set at creation time and are not reset; these are typically dimensions used in other interstitial variables. If the value of a variable must be remembered from one call to the next, it should not be in the interstitial or diagnostic data types. 
• Follow the guidelines outlined in the Technical Documentation to add input/output variable arguments to .meta files.