Configuration, Building and Installation for Different Systems

Table of Contents

• Requirements
• Getting YAC
  • Entire repository
  • Specific Release
• Building YAC
  • Building on HPC System at DKRZ (gcc 11.2.0, OpenMPI 4.1.2)
  • Building on macOS 13.1 (Ventura) Apple M1 (homebrew gcc 12.2.0, OpenMPI 4.1.4, netcdf 4.9.0)
  • Building on Ubuntu 24.04 or Ubuntu 25.10 (OpenMPI 4.1.6)
    • Building on Older Ubuntu Versions
      • Ubuntu 20.04
  • Building on Windows (via WSL)
    • Prerequisites & setup
    • Common pitfalls & workarounds
• Examples
• Linking with YAC

Requirements

• MPI
• LAPACK
  • If no external interface is provided (e.g. MKL, ATLAS, ...) the bundled (very limited) version of CLAPACK library is used.
• libfyaml
  • Only required for YAC MCI library.
• yaxt (see Installing yaxt)
• NetCDF
  • Not mandatory, but without it features like writing or reading weight files will be deactivated.
• libmtime
  • A bundled version is included in YAC, but an external one can be specified.
  • Only required for YAC MCI library.
• Autoconf
  • Only required for configuration if you are not using a release (e.g., develop version).
• Doxygen (recommended version 1.11.0, check doxygen --version)
  • Only required if you want to build the documentation via doxygen doc/Doxyfile
• Graphviz
  • Only required if you want to build the documentation

Getting YAC

Clone public repository of YAC.

Entire repository

Get the entire repository and optionally check out a specific release

git clone https://gitlab.dkrz.de/dkrz-sw/yac.git
git -C yac checkout <release_tag>

Specific Release

Alternatively get only the code for a specific release.

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

Building YAC

After cloning the repositotory the folder yac contains all source code and other files that belong to the software YAC.

For building YAC it is recommended to use a separate directory. The location is arbitrary. To create the build directory inside the folder yac execute the following commands:

cd yac
mkdir build

In the remainder of this section the folder yac will be referred to as <yac_repo_dir>, the folder <yac_repo_dir>/build will be referred to as <yac_build_dir>. The folder <yaxt_inst_dir> denotes the directory where yaxt was installed, and <yac_inst_dir> specifies the target directory where yac should be installed.

Unless explicitly specified when configuring the build directory, all YAC libraries, unit tests, examples, and YAC tools will be built.

Building on HPC System at DKRZ (gcc 11.2.0, OpenMPI 4.1.2)

Information about the HPC-system Levante at DKRZ can be found here.

Load toolchain

module purge
module load \
        gcc/11.2.0-gcc-11.2.0 \
        openmpi/4.1.2-gcc-11.2.0 \
        netcdf-c/4.8.1-openmpi-4.1.2-gcc-11.2.0 \
        hdf5/1.12.1-openmpi-4.1.2-gcc-11.2.0 \
        intel-oneapi-mkl/2022.0.1-gcc-11.2.0
spack load python@3.9.9%gcc@11.2.0/fwvsvi6

If you need Python bindings (see --enable-python-bindings below), make sure to set up your Python virtual environment correctly by following the first steps #setup venv here.

YAC releases already contain a configure-script, if another YAC version is used (e.g. master-branch), it has to be generated.

cd <yac_repo_dir>
test -f ./configure || ./autogen.sh

Configure build directory

cd <yac_build_dir>
<yac_repo_dir>/configure \
        CC=mpicc \
        FC=mpif90 \
        --disable-mpi-checks \
        --disable-silent-rules \
        --enable-concurrent-mpi-tests \
        --enable-python-bindings \
        --with-fyaml-root=/sw/spack-levante/libfyaml-0.7.12-fvbhgo \
        --with-netcdf-root=/sw/spack-levante/netcdf-c-4.8.1-6qheqr \
        --with-yaxt-root=<yaxt_inst_dir> \
        MKL_CFLAGS="`pkg-config --cflags mkl-static-lp64-seq`" \
        MKL_CLIBS="`pkg-config --libs mkl-static-lp64-seq`" \
        --prefix=<yac_inst_dir>

Build

cd <yac_build_dir>
make -j8

Run tests

cd <yac_build_dir>
make -j8 check

Install

cd <yac_build_dir>
make install

Building on macOS 13.1 (Ventura) Apple M1 (homebrew gcc 12.2.0, OpenMPI 4.1.4, netcdf 4.9.0)

Generate configure-script in source directory (if required)

cd <yac_repo_dir>
test -f ./configure || ./autogen.sh

Configure build directory (with external libmtime and LAPACK)

cd <yac_build_dir>
<yac_repo_dir>/configure \
        --with-netcdf-root=/opt/homebrew \
        --with-fyaml-root=/opt/homebrew \
        --with-yaxt-root=<yaxt_inst_dir> \
        --disable-lib-only \
        --without-external-mtime \
        --enable-silent-rules \
        CC=/opt/homebrew/bin/mpicc \
        FC=/opt/homebrew/bin/mpif90 \
        CFLAGS="-g -Wall" \
        FCFLAGS="-g -Wall -fimplicit-none" \
        MPI_LAUNCH="$(which mpirun) --map-by socket:OVERSUBSCRIBE"

Build

cd <yac_build_dir>
make -j8

Run tests

cd <yac_build_dir>
make -j8 check

Install

cd <yac_build_dir>
make install

Building on Ubuntu 24.04 or Ubuntu 25.10 (OpenMPI 4.1.6)

Warning

There is a bug with OpenMPI's MPMD on Ubuntu 25.04. Therefore, the use of Ubuntu 25.04 is not recommended with YAC. Refer to github.com/open-mpi/ompi/issues/13303 for further information.

First, install some basic dependencies via the package manager:

apt install build-essential git libtool openmpi-bin libopenmpi-dev \
            libnetcdf-dev libfyaml-dev

If you want to --enable-python-bindings (and test them) you also need:

apt install libpython3-dev python3-setuptools python3-numpy python3-mpi4py \
            python3-netcdf4 python3-matplotlib python3-isodate cython3

Note

uxarray does not offer installation via apt. This will lead to some tests being skipped. If you still want to run these tests create a venv with the option --system-site-packages and install uxarray using pip:

cd <yac_build_dir>
python3 -m venv --system-site-packages <venv_path>
source <venv_path>/bin/activate
pip install uxarray

Make sure to activate the venv before running the tests.

If you prefer installing the Python dependencies in a virtual environment, please enter the following:

cd <yac_build_dir>
python3 -m venv <venv_path>
source <venv_path>/bin/activate
pip install -r <yac_repo_dir>/python/requirements.txt

If you want to build the documentation you also need:

apt install doxygen graphviz

Please consider installing Doxygen 11.1.0 if you experience issues in the documentation.

Generate configure-script in source directory

cd <yac_repo_dir>
test -f ./configure || ./autogen.sh

Configure build directory (with external libmtime and LAPACK)

cd <yac_build_dir>
<yac_repo_dir>/configure \
        CC=mpicc \
        FC=mpif90 \
        --enable-mpi-checks \
        --enable-silent-rules \
        --enable-concurrent-mpi-tests \
        --enable-python-bindings \
        --with-yaxt-root=<yaxt_inst_dir> \
        CFLAGS="-g -Wall" \
        FCFLAGS="-g -Wall -fimplicit-none" \
        MPI_LAUNCH="mpirun --oversubscribe" \
        --prefix=<yac_inst_dir>

Build

cd <yac_build_dir>
make -j8

Run tests

cd <yac_build_dir>
make -j8 check

Install

cd <yac_build_dir>
make install

Note

Instead of setting MPI_LAUNCH during configuration above, you can configure your MPI to use the --oversubscribe option per default.

• OpenMPI 4 and earlier: Create the file $HOME/.openmpi/mca-params.conf and insert the following lines:

  rmaps_base_oversubscribe=1
  orte_create_session_dirs=1

• OpenMPI 5: Create the file $HOME/.prte/mca-params.conf and insert the line:

  rmaps_default_mapping_policy = :oversubscribe

Building on Older Ubuntu Versions

Note

Information in this section may be outdated but still useful if you have to use an older version of Ubuntu. Generally, it is recommended to use a recent OS version.

It is also possible to build YAC on older Ubuntu versions by following the instructions above. However, you might have to build some dependencies from source. The following versions have been used to build YAC:

Ubuntu 20.04

You will have to build libfyaml-dev from source because it is not provided in the package repositories:

1. Please clone github.com/pantoniou/libfyaml and follow the instructions for building and installation. It is recommended to install libfyaml into a user-specified directory <libfyaml_inst_dir> by using the --prefix option: ./configure --prefix=<libfyaml_inst_dir>
2. The remaining steps are almost identical as for a recent Ubuntu. Please add the option ./configure ... --with-fyaml-root=<libfyaml_inst_dir> ... when configuring the build process of YAC to make sure libfyaml can be found during the YAC build.

Building on Windows (via WSL)

Warning

YAC is not natively supported on Windows. Once WSL is set up and Ubuntu 24.04 is running, building YAC proceeds similarly to the Building on Ubuntu 24.04 or Ubuntu 25.10 (OpenMPI 4.1.6) instructions.

We strongly recommend installing Ubuntu 24.04 under the Windows Subsystem for Linux (WSL) and then following the instructions in the Building on Ubuntu 24.04 section.

Prerequisites & setup

• On your Windows host, enable WSL and install Ubuntu 24.04 (e.g. via Microsoft Store).
• Launch the Ubuntu 24.04 shell. Inside that environment, install all required dependencies (MPI, libfyaml, NetCDF, etc.) and follow the build instructions for YAC exactly as described in the Building on Ubuntu 24.04 or Ubuntu 25.10 (OpenMPI 4.1.6) section. Attention:** Please skip the testing step and do not run make check (see Common pitfalls & workarounds for details).
• You may optionally share code (e.g. via /mnt/c/...) between Windows and WSL, but ensure builds happen inside WSL to avoid toolchain conflicts.

Common pitfalls & workarounds

• WSL instability / crashes: Occasionally WSL may crash or hang without obvious reason. One known reason for this behavior is if you tried to run the (parallel) tests. In such cases, rebooting the WSL environment explicitly may help. From a Windows command prompt or PowerShell, run:

  wsl --shutdown
  wsl

  This forces a full restart of the WSL VM.

• Tests do not work under WSL: The make check (or ctest) step is known to fail in WSL environments. Therefore, skip the test step when building under WSL. Just build and install (make → make install) without running the tests.
• Filesystem / performance differences: If your source tree or build directory resides on the mounted Windows filesystem (e.g. /mnt/c/...), you may observe slower I/O or permission issues. For better performance, keep the repository and build directories inside the WSL native filesystem (e.g. under ~/yac).

Examples

By default together with the YAC library a couple of examples will be built. They can be found in:

<yac_build_dir>/examples/<example_name>

Additional information on each example is available in:

<yac_repo_dir>/examples/<example_name>/README

Linking with YAC

Using the pkg-config tool, the variables for linking YAC to your program can be extracted.

Set search path for pkg-config

export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:<yac_inst_dir>/lib/pkgconfig

Getting Parameters for C-Interface

CC=`pkg-config --variable=cc yac-mci`
YAC_CFLAGS=`pkg-config --variable=cflags yac-mci`
YAC_CLIBS=`pkg-config --variable=clibs yac-mci`

Getting Parameters for Fortran-Interface

FC=`pkg-config --variable=fc yac-mci`
FCFLAGS=`pkg-config --variable=fcflags yac-mci`
FCLIBS=`pkg-config --variable=fclibs yac-mci`