YAC

YAC is a coupling library for Earth system models.

Documentation

An extensive documentation with:

• user guide
• interface reference
• release information
• building instructions
• detailed information on interpolation options
• ...

can be found here:

https://dkrz-sw.gitlab-pages.dkrz.de/yac/

Requirements

• MPI
• LAPACK (a bundled, limited CLAPACK fallback is used if no external implementation is found)
• libfyaml (only required for the MCI library)
• yaxt
• NetCDF (optional; without it, features like reading/writing weight files are disabled)
• libmtime (bundled version included; only required for the MCI library)

See the documentation for the full list of requirements, including those only needed for building from a non-release checkout or building the documentation itself.

Getting YAC

git clone https://gitlab.dkrz.de/dkrz-sw/yac.git

To get only the code for a specific release:

git clone --depth 1 --branch <release_tag> https://gitlab.dkrz.de/dkrz-sw/yac.git

Installing the Python bindings from PyPI

The Python bindings can be installed directly from PyPI:

pip install yac

By default, pip install automatically detects available MPI compilers and builds YAC with Python bindings from source. See the Python bindings documentation for optional extras (pip install yac[full]) and how to point the build at a specific MPI, yaxt, or NetCDF installation via CMAKE_ARGS.

[!TIP] On HPC systems it is recommended to pass --no-binary=yac to the pip install command, so that YAC is always built from source against the locally available MPI installation and other system libraries, instead of a prebuilt wheel:

pip install --no-binary=yac yac

Building YAC

YAC can be built either with Autotools or with CMake. Detailed, system-specific build instructions (Levante, macOS, Ubuntu, Windows/WSL, ...) are provided in the documentation.

Autotools

./autogen.sh
mkdir build && cd build
../configure ...
make

CMake

YAC also provides CMake support as an alternative build system, supporting all of the same features (building the core, utils and MCI libraries with C and Fortran interfaces, Python bindings, tools, examples and tests). It requires CMake 3.18 or later.

mkdir build_cmake && cd build_cmake
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo \
      -DBUILD_TESTING=ON \
      -DYAC_ENABLE_PYTHON=ON \
      -Dyaxt_ROOT=<yaxt_inst_dir> \
      -DCMAKE_INSTALL_PREFIX=<yac_inst_dir> \
      ..
cmake --build . --parallel 8

Note that cmake --install installs the YAC libraries, headers and tools, but not the Python bindings. See the CMake documentation for details, including configuration options and how to consume YAC from a downstream CMake project via find_package(YAC).

Testing YAC

With Autotools, the following runs the test suite:

make -j8 check

```sh
ctest --output-on-failure --parallel 8

Examples

The examples directory contains a number of C, Fortran, and Python use case examples, which can be used as a reference on how to use the YAC' interfaces. Each example therein contains its own README describing its purpose and how to use it. We also provide examples to test the coupling between realistic grids. These examples can also be used to study the behaviour of the various interpolations and the interpolation stack.

Contact

• Moritz Hanke - hanke at dkrz.de
• Nils-Arne Dreier - dreier at dkrz.de
• Benjamin Rodenberg - rodenberg at dkrz.de

License

BSD License

• see copyright notice in files.
• for mtime source code see COPYING within mtime directory.