Metadata-Version: 2.2
Name: yac
Version: 3.21.0
Summary: Yet Another Coupler 
Author: The YAC Authors
License: BSD-3-Clause
Requires-Python: >=3.9
Requires-Dist: numpy
Provides-Extra: full
Requires-Dist: mpi4py; extra == "full"
Requires-Dist: netcdf4; extra == "full"
Requires-Dist: uxarray; extra == "full"
Requires-Dist: scipy; extra == "full"
Requires-Dist: matplotlib; extra == "full"
Requires-Dist: isodate; extra == "full"
Description-Content-Type: text/markdown

<!--
Copyright (c) 2026 The YAC Authors

SPDX-License-Identifier: CC-BY-4.0
-->

# YAC

[![pipeline status](https://gitlab.dkrz.de/dkrz-sw/yac/badges/master/pipeline.svg)](https://gitlab.dkrz.de/dkrz-sw/yac/-/commits/master)
[![PyPI](https://img.shields.io/pypi/v/yac.svg)](https://pypi.org/project/yac/)
[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://gitlab.dkrz.de/dkrz-sw/yac/-/blob/master/LICENSES/BSD-3-Clause.txt)

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](https://www.mpi-forum.org/)
- LAPACK (a bundled, limited CLAPACK fallback is used if no external
  implementation is found)
- [libfyaml](https://github.com/pantoniou/libfyaml) (only required for the MCI
  library)
- [yaxt](https://gitlab.dkrz.de/dkrz-sw/yaxt)
- [NetCDF](https://www.unidata.ucar.edu/software/netcdf/) (optional; without
  it, features like reading/writing weight files are disabled)
- [libmtime](https://gitlab.dkrz.de/icon-libraries/libmtime) (bundled version
  included; only required for the MCI library)

See the [documentation](https://dkrz-sw.gitlab-pages.dkrz.de/yac/d1/d9f/installing_yac.html)
for the full list of requirements, including those only needed for building
from a non-release checkout or building the documentation itself.

## Getting YAC

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

To get only the code for a specific release:

```sh
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:

```sh
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](https://dkrz-sw.gitlab-pages.dkrz.de/yac/pythonbindings.html)
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:
> ```sh
> 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

```sh
./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.

```sh
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](https://dkrz-sw.gitlab-pages.dkrz.de/yac/cmake.html) 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:
```sh
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.
