ICON EBFM ComIn Plugin

ComIn Plugin to implement EBFM coupling ICON.

Preparations

Both dependencies below are built by .github/workflows/ctest.yaml on every push, so that workflow is the executable version of this section — check there for the exact versions and flags currently known to work.

YAC

This plugin uses YAC to connect ICON to EBFM. Install yaxt and YAC as described in the YAC documentation; installing both into the same $YAC_INSTALL_DIR keeps the steps below to a single CMAKE_PREFIX_PATH.

find_package(YAC) resolves YAC in CMake config mode, so it is recommended to build YAC with its CMake build system.

ComIn

Clone ComIn where you want it. This plugin needs experimental API from branch 166-yac-named-points main.c will not build against the default branch:

git clone --branch 166-yac-named-points https://gitlab.dkrz.de/icon-comin/comin.git $COMIN_REPO_DIR
cd $COMIN_REPO_DIR
cmake -B build -DCOMIN_ENABLE_EXAMPLES=OFF -DBUILD_TESTING=ON -DCOMIN_ENABLE_REPLAY_TOOL=ON -DCOMIN_ENABLE_YAC=ON -DCMAKE_PREFIX_PATH=$YAC_INSTALL_DIR .
make -C build

ComIn is used from its build directory (see Build below); no cmake --install needed.

Build

From this folder

export ComIn_DIR=$COMIN_REPO_DIR/build
cmake -B build -DCMAKE_PREFIX_PATH=$YAC_INSTALL_DIR .
make -C build

Run Tests

The first ctest run downloads ComIn's test_nwp_R02B04 replay data from gitlab.dkrz.de (test download_test_data), so it needs network access.

cd build
ctest
# if you want to run individual tests and see their output
ctest -R ebfm_comin_replay -V

# 2: INFO(ebfm_comin): Hello ComIn!
# ...
# 2: INFO(ebfm_comin): See you later ComInator!

Run Plugin with fake data and real EBFM

Once the plugin passes its own replay tests above, you can go one step further and couple it to the real EBFM model instead of the ebfm_receiver from test/receiver.c. This still runs against the fake ICON data from test/fake.c (the tas_fake plugin).

The invocation below has been run end to end against test_nwp_R02B04 and completes with EBFM exchanging all 9 fields over 5 coupling steps.

Additional requirements

• EBFM is installed with coupling support (pip install 'EBFM[cpl]') into a venv. Follow EBFM's own installation docs.
• Make sure to install YAC from source with Python support. You will need the C and Python interface of YAC, and ComIn has to be built against that same YAC. (The yac package from PyPI does ship a C interface, but it is unusable for a CMake build: find_package(YAC) fails on its own find_dependency(yaxt), and its pkg-config files point at the manylinux build container's /usr/local/lib. See doc/ebfm_coupling_details.md.)
• Activate the venv. You may also use $VIRTUAL_ENV as -DCMAKE_PREFIX_PATH and -DCMAKE_INSTALL_PREFIX during YAC installation to keep everything in one place.
• You've already built this plugin as described above in the build section.

Run it from this repo's build/ebfm_comin_cpl test directory:

export EBFM_COMIN_REPO_DIR=/path/to/this/repo
export COMIN_REPLAY_BIN=/path/to/comin/build/replay_tool/comin_replay
export EBFM_REPO_DIR=/path/to/your/EBFM/checkout   # for its bundled example mesh

cd "$EBFM_COMIN_REPO_DIR/build/ebfm_comin_cpl"
# clean up (if existing) & create some empty folders
rm -r output
mkdir output
rm -r out
mkdir out

mpiexec -n 1 "$COMIN_REPLAY_BIN" ebfm_comin_cpl.nml \
      : -n 1 ebfm \
          --elmer-mesh "$EBFM_REPO_DIR/examples/elmer_wo_DEM/MESH" \
          --elmer-mesh-crs-epsg 3413 \
          --coupler-config "$EBFM_COMIN_REPO_DIR/examples/coupling.yaml" \
          --couple-to-icon-atmo \
          --no-shading \
          --start-time "2014-06-01T00:00:00" \
          --end-time "2014-06-01T00:25:00" \
          --time-step PT5M

Notes about the parameters used in ebfm:

• the --start-time and --end-time must match the replay data
• --time-step PT5M must match both models' timesteps
• the directories output and out must exist

Use this plugin in ICON

untested!

After compilation you need to do the following steps.

Prerequisites

• ICON must be built with --enable-comin, using a ComIn version compatible with the one this plugin was built against (matching major version, host minor version at least as high as the plugin's).
• ICON must be run with AES physics. This plugin reads the near-surface temperature tas, which is only diagnosed by the AES physics package (mo_aes_phy_memory); under NWP physics tas does not exist, and the plugin will abort as soon as it tries to access the variable.
• Not yet verified against a real coupled run. main.c defines its YAC fields on top of ICON's own grid by looking it up as yac_cget_grid_id("icon_atmos_grid") / yac_cget_points_id(grid_id, YAC_LOCATION_CELL, "cell_centers") (see yac_example.py). This assumes ICON's own coupling code registers its cell-center point set under the name "cell_centers" — I could not confirm this by reading ICON's feature_icono2elmer branch (no occurrences of that name in src/coupling), and the replay test does not exercise yac_cenddef() so it cannot catch a mismatch either. Confirm this against a real ICON run (or a replay test with a second, real YAC participant, cf. comin's own yac_input test) before relying on it.
• The component name this plugin registers (ebfm_comin) and the coupling period (currently PT3H in ebfm_dummy/config/coupling_icon_atmo.yaml) need to be agreed with whatever the real EBFM-side coupling config targets.

Make the plugin discoverable

Add the directory containing libebfm_comin.so to LD_LIBRARY_PATH in your ICON run script, e.g.

export LD_LIBRARY_PATH="/path/to/this/repo/build:$LD_LIBRARY_PATH"

or, if your run script's basedir variable is set to your ICON build directory, use the run script helper function instead:

add_comin_setup "/path/to/this/repo/build"

Add the plugin to comin_nml

Add the following to your comin_nml (part of ICON's atmo_namelist file):

&comin_nml
  plugin_list(1)%name           = "ebfm_comin"
  plugin_list(1)%plugin_library = "libebfm_comin.so"
/

To deactivate the plugin, remove (or comment out) this block.

pre-commit

This project uses pre-commit hooks for some tasks described in detail below. To setup pre-commit please do the following:

pipx install pre-commit
pre-commit install

Copyright and licensing

This project uses REUSE to track information regarding copyright and licensing. Therefore, all files in this repository are required to provide the corresponding information. Please refer to the documentation of REUSE for details.

You can use pre-commit to automatically check if all files in the repository provide the necessary information:

pre-commit run reuse --all-files

If files are missing copyright information you can use the following command to annotate with reuse:

reuse annotate --license BSD-3-Clause --copyright "The ICON EBFM ComIn Plugin Authors" path/to/new/file