README.md

Generic C++ library hbrs-mpl for scientific computing at HPC clusters

hbrs-mpl is a experimental generic C++17 library (GitHub.com, H-BRS GitLab) for distributed scientific computing at HPC clusters. Our research goal is to be able to codify complex algorithms like singular value decomposition (SVD) using abstract, mathematical notation without sacrificing space and time efficiency. We use meta programming to evaluate expressions at compile-time and thus avoid any negative performance impact on run-time. We apply generic techniques with the help of C++ templates to write reusable and robust components.

Its development started in 2015 as a research project at Bonn-Rhein-Sieg University of Applied Sciences, from 2016-2019 it was funded partly by BMBF project AErOmAt.

Primary use cases for hbrs-mpl are:

• hbrs-theta_utils (GitHub.com, H-BRS GitLab), a postprocessing tool to CFD solvers TAU and THETA for data-driven modal decompositions
• python-edamer (GitHub.com, H-BRS GitLab), a Python 3 library for exascale data analysis and machine learning applications

⚠️ WARNING: This code is still under development and is not ready for production yet. Code might change or break at any time and is missing proper documentation. :warning:

⚠️ DEPRECATION NOTICE: Apparently, this code meets the inevitable fate of many state-funded research projects. It has not been actively worked on since 2020. Software consists of teams of people. If you want people to continue developing a project after it ceases to be their personal interest, fund them for it. ⚠️

Under the hood

hbrs-mpl provides algorithms for

• linear algebra, e.g. matrix operations like hbrs::mpl::fn::multiply and hbrs::mpl::fn::transpose
• numerical linear algebra, e.g. eigenvalue decomposition, singular value decomposition (SVD)
• statistics, e.g. Principal Component Analysis (PCA) / Proper Orthogonal Decomposition (POD)
• time-dependent statistics, e.g. Dynamic Mode Decomposition (DMD)

hbrs-mpl's functions are mostly geared towards compatibility with MATLAB's API, because the latter has a strong focus on mathematical notations, is properly documented and useful for rapid prototyping.

hbrs-mpl provides local and distributed data structures for matrices, vectors and sequences.

hbrs-mpl builds heavily on Elemental for distributed data structures and linear algebra algorithms and Boost.Hana for meta programming and generic coding.

The full tech stack consists of:

• C++17 for generic, functional and efficient library code
• C++ library Elemental
• C++ metaprogramming library Boost.Hana
• MATLAB Coder to generate C code from MATLAB code which we then use exclusively in unit tests to compare results of hbrs-mpl's algorithms to MATLAB or rather its LAPACK libraries. Note, hbrs-mpl compiles just fine without MATLAB!
• MPI for distributed computations
• Boost.Test for unit tests, e.g. hbrs::mpl::fn::svd and hbrs::mpl::fn::pca
• CMake 3 and hbrs-cmake to build, export and install our library
• GitLab CI to continuously build and test our code against different compilers
• Python 3 to generate missing headers

How to build, install and run code using Docker or Podman

For a quick and easy start into developing with C++, a set of ready-to-use Docker/Podman images jm1337/debian-dev-hbrs and jm1337/debian-dev-full (supports more languages) has been created. They contain a full development system including all tools and libraries necessary to hack on distributed decomposition algorithms and more (Docker Hub, source files for Docker images).

Install Docker or Podman

• On Debian 10 (Buster) or Debian 11 (Bullseye) just run sudo apt install docker.io or follow the official install guide for Docker Engine on Debian
• On Ubuntu 18.04 LTS (Bionic Beaver) and Ubuntu 20.04 LTS (Focal Fossa) just run sudo apt install docker.io (from bionic/universe and focal/universe repositories) or follow the official install guide for Docker Engine on Ubuntu
• On Windows 10 follow the official install guide for Docker Desktop on Windows
• On Mac follow the official install guide for Docker Desktop on Mac
• On Fedora, Red Hat Enterprise Linux (RHEL) and CentOS follow the official install guide for Podman

Setup and run container

# docker version 18.06.0-ce or later is recommended
docker --version

# fetch docker image
docker pull jm1337/debian-dev-hbrs:bullseye

# log into docker container
docker run -ti jm1337/debian-dev-hbrs:bullseye
# or using a persistent home directory, e.g.
docker run -ti -v /HOST_DIR:/home/devil/ jm1337/debian-dev-hbrs:bullseye
# or using a persistent home directory on Windows hosts, e.g.
docker run -ti -v C:\YOUR_DIR:/home/devil/ jm1337/debian-dev-hbrs:bullseye

Podman strives for complete CLI compatibility with Docker, hence you may use the alias command to create a docker alias for Podman:

alias docker=podman

Build and run code inside container

Execute the following commands within the Docker/Podman container:

# choose a compiler
export CC=clang-10
export CXX=clang++-10
# or
export CC=gcc-10
export CXX=g++-10

# fetch, compile and install prerequisites
git clone --depth 1 https://github.com/JM1/hbrs-cmake.git
cd hbrs-cmake
mkdir build && cd build/
# install to non-system directory because sudo is not allowed in this docker container
cmake \
    -DCMAKE_INSTALL_PREFIX=$HOME/.local \
    ..
make -j$(nproc)
make install
cd ../../

# fetch, compile and install hbrs-mpl
git clone --depth 1 https://github.com/JM1/hbrs-mpl.git
cd hbrs-mpl
mkdir build && cd build/
cmake \
 -DCMAKE_INSTALL_PREFIX=$HOME/.local \
 -DHBRS_MPL_ENABLE_ELEMENTAL=ON \
 -DHBRS_MPL_ENABLE_MATLAB=OFF \
 -DHBRS_MPL_ENABLE_TESTS=ON \
 -DHBRS_MPL_ENABLE_BENCHMARKS=ON \
 ..
make -j$(nproc)
ctest --verbose --output-on-failure
make install

For more examples on how to build and test this code see .gitlab-ci.yml.

License

GNU General Public License v3.0 or later

See LICENSE.md to see the full text.

Author

Jakob Meng @jm1 (GitHub.com, Web)