ICON Granules – Structure and Components#
Introduction#
The ICON source code contains more than 900 modules. On average, each module contains 13 Fortran USE statements, resulting in a densely coupled dependency structure across the code base. To address this issue, ICON introduces a standardized decomposition into independent code units, referred to as Granules. A granule is defined as a self-contained software unit with explicitly controlled dependencies that allows for separate compilation and execution.
This granularization of ICON is intended to support several key requirements of future model development, including:
improved accessibility and understandability of the code base,
enhanced support for language interoperability,
more modular and fine-grained testing strategies,
and increased reuse of model components, including their application in machine learning workflows and the integration of AI-based methods into ICON.
Structure of the Granule#
The general structure of these granules is discussed using the Cloud-Cover-KOE Granule, which serves as a reference implementation for subsequent granules. See the following figure for an illustration of the Cloud-Cover-KOE granule.
Together with the required ICON-specific components, a granule consists of the following parts:
Inside the Granule#
Granule Scheme (
physics_granules/cldcov_koe/mo_cldcov_koe): The innermost part of the granule. It holds the actual physical scheme. Typically the scheme is divided intoInit Scheme: Pre-calculations executed during the init phase (
cldcov_koe_init). This phase may also be required for experiment-specific configurations, for example when applying parameter perturbations.Run Scheme: Update of model variables during the time loop (
cldcov_koe).
Granule Types (
physics_granules/cldcov_koe/mo_cldcov_koe_types) : Defines user‑defined types that mediate communication with the granule. The types distinguish four data flows:Input – data provided by ICON for the init phase, e.g. namelist parameters.
Granule‑internal – Constant parameters calculated by the init scheme. They define the granule configuration and are passed to the run scheme routine; they are not visible outside the granule.
Variables – ICON variables that the granule scheme may read and/or modify during the run phase.
Export – information that other granules can use (e.g., internal values shared to guarantee consistency).
Public Layer (
physics_granules/cldcov_koe/mo_cldcov_koe_public): The only module that should be called from outside the granule. It provides two public procedures:cldcov_koe_public_init– calls the internal init scheme (cldcov_koe_init).cldcov_koe_public– calls the internal run scheme (cldcov_koe).
Both procedures use the granule types as arguments, which yields a short, homogeneous and transparent syntax for external / ICON calls. Inside the granule the scheme routines can be invoked by the public routines directly without the granule types, giving developers flexibility while keeping the external interface stable.
Outside of the Granule in ICON#
Driver (
atm_phy_nwp/mo_nwp_cldcov_koe_driver): From ICON’s perspective this is the last layer outside the granule. Here dependencies to ICON are resolved, the granule‑types are filled with input data, and the public procedures are called. The driver holds an array of granule-internal structures, where each element corresponds to a different domain. This allows running the granule with different configurations across multiple domains.Interface (
atm_phy_nwp/mo_cldcov_interface): Since several cloud‑cover schemes are available in ICON, the interface distinguishes between them and shares variables and/or function calls used by multiple schemes.