The CCPP-framework provides end users  with the ability to plug in different schemes and reorder schemes with minimal effort.  To provide that functionality, the following steps need to be taken when introducing a new scheme.  

IMPORTANT NOTE – MUSICBOX AND THE CCPP-FRAMEWORK ARE EXPECTED TO EVOLVE IN THE NEAR FUTURE AND THE FOLLOWING DIRECTIONS WILL MOST LIKELY NOT APPLY TO FUTURE VERSIONS.

CCPP is fully documented at https://dtcenter.org/gmtb/users/ccpp/docs/CCPP-DevGuide-v2.pdf.  While we will describe changes that are required for adding a new scheme, the full details of the CCPP framework are beyond the scope of this section.  We encourage users to refer to the CCPP documentation for additional information.

The CCPP framework does a prebuild (which generates fortran code from the metadata and performs other prebuild steps).  The prebuild takes the specially formatted metadata and generates new "cap" files as well as matching variables using their standard_names, checking units, rank, etc. and creating accessory fortran code.  All of these details happen behind the scenes and should not need to be known to users of MusicBox.

In this section we will be creating a new script called ABCD and introducing a new scheme called XXX.  These directions are assuming that the host model is still MusicBox.

CODE CHANGES

Schemes must have the following so that the ccpp-framework will be able to auto-generate the necessary code

• Have a module XXX.90 which contains at a minimum routines: XXX_init, XXX_run and XXX_finalize

• The argument list for the init, run and finalize methods are extensively documented with the specialized tables at the top of each routine (the Argument tables that are comment lines)  This information is processed by the cppp prebuild step to create the necessary code to link the host model with the routine

  • NOTE - This metadata format will be changing in the next version of the ccpp-framework

INFRASTRUCTURE CHANGES

ccpp_prebuild_config_MusicBox_ABCD.py

Create a new script called ccpp_prebuild_config_MusicBox_ABCD.py.   The directions below are assuming you are starting with an already established script such as  MusicBox/ccpp-framework/scripts/ccpp_prebuild_config_MusicBox.py and making modifications for your scheme XXX.

• SCHEME_FILES: the list of MICM modules.  You will need to add XXX to this list. 

MusicBox_host/suites/suite_MusicBox_ABCD.xml

• This file contains the schemes that will be called (and the order in which they will be called at the init, run and finalize steps).  The first set of schemes are the list of both the init and run methods.  If XXX only needs either an init or a run method, the other routine must still be supplied as an empty routine.

• The library which which contains the schemes is listed at the top of this file (and most likely should not be changed)

HOST MODEL CAP (MusicBox_host/src/MusicBox_var_defs.f90)

• This file includes the information for all variables about which the host model needs to know.  Add any variables which appear in the calling list for XXX's _init, _run or _finalize routine which do not already reside in this file.

MICM_chemistry/CMakeLists.txt

• "set (SCHEMES" section 

  • add the XXX file.  If XXX calls lower level routines that exist is separate files, these files need to be included here as well (so that they will be compiled)

• "set (CAPS" section

  •  include the XXX filename with “_cap” appended - these files are autogenerated using the Argument table information.  (Lower level routines are not included in this list)