.. _ConfigBuildOptions:

*****************************************
CCPP Configuration and Build Options
*****************************************
While the :term:`CCPP Framework` code, consisting of a single Fortran source file and associated metadata file, can be compiled and tested independently, the :term:`CCPP Physics` code can only be used within a :term:`host modeling <host model>` system that provides the variables required to execute the physics. As such, it is advisable to integrate the CCPP configuration and build process with the host model build system. Part of the build process, known as the *capgen* step since it precedes compilation, involves running a Python script that performs multiple functions. These functions include configuring the *CCPP Physics* for use with the host model and autogenerating FORTRAN code to communicate variables between the physics and the dynamical core. The *capgen* step will be discussed in detail in :numref:`Chapter %s <CCPPcapgen>`.

The :term:`SCM` and the :term:`UFS Atmosphere` are supported for use with the CCPP. In the case of the UFS Atmosphere as the host model, build configuration options can be specified as cmake options to the ``build.sh`` script for manual compilation or through a regression test (RT) configuration file. Detailed instructions for building the UFS Atmosphere and the SCM are discussed in the
`UFS Weather Model User Guide <https://ufs-weather-model.readthedocs.io/en/release-public-v3/BuildingAndRunning.html#building-the-weather-model>`_
and the `SCM User Guide <https://dtcenter.org/sites/default/files/paragraph/scm-ccpp-guide-v6-0-0.pdf>`_.
For both SCM and UFS the ``ccpp_capgen.py`` script is run automatically as a step in the build system,
although it can be run manually for debugging purposes.

Lists containing scheme and host metadata files, along with a list of Suite Definition Files, must be provided to ``ccpp_capgen.py``. For the ccpp-scm and ufs-weather-model repositories, these file lists are defined within the CMakeLists, just prior to the call the ``ccpp_capgen.py``. When calling ``ccpp_capgen.py``, the following sequence is performed:

* Parse metadata and corresponding source file lists and check for consistency. This is the CCPP validation stage.

* Using Suite Definition File(s), autogenerate CCPP physics Group and Host Caps (a.k.a. physics drivers).

* ``ccpp_capgen.py`` creates a ``datatable`` that contains source and dependency files lists. These lists are added to the build target within CMakeLists.txt

:numref:`Figure %s <ccpp_static_build>` depicts the main functions of the
``ccpp_capgen.py`` script for the build.  Using information included in the configuration file
and the :term:`SDF`\ (s), the script parses the SDF(s) and only matches provided/requested variables that are used
within the particular physics suite(s).  The script autogenerates software :term:`caps <physics cap>` for the physics suite(s) as a
whole and for each physics :term:`group` as defined in the SDF(s), as well as for an API that the host model calls into
from the (manually written) host model cap. At runtime, a single SDF is used to select the
suite that will be executed in the run. This arrangement allows for efficient variable recall (which
is done once for all physics :term:`schemes <scheme>` within each group of a suite), leads to a reduced memory footprint of the
CCPP, and speeds up execution.

.. _ccpp_static_build:

.. figure:: _static/ccpp_static_build.png
    :align: center
    :width: 800px
    :height: 400px

    *This figure depicts an example of the interaction between an atmospheric model and CCPP Physics for one timestep, and a single SDF, with execution progressing toward the right.  The “Atmosphere Driver” box represents model superstructure code, perhaps responsible for I/O, time-stepping, and other model component interactions.  Software caps are autogenerated for the suite and physics groups, defined in the SDF provided to the* ``ccpp_capgen.py`` *script. The suite must be defined via the SDF at capgen time. When multiple SDFs are provided during the build step, multiple suite caps and associated group caps are produced, but only one is used at runtime.*