\( \newcommand{\blu}[1]{{\color{blue}#1}} \newcommand{\red}[1]{{\color{red}#1}} \newcommand{\grn}[1]{{\color{green!50!black}#1}} \newcommand{\local}{_i} \newcommand{\inv}{^{-1}} % Index for interface and interior \newcommand{\G}{\Gamma} \newcommand{\Gi}{\Gamma_i} \newcommand{\I}{{\cal I}} \newcommand{\Ii}{\I_i} % Matrix A \newcommand{\A}{{\cal A}} \newcommand{\Ai}{\A\local} \newcommand{\Aj}{\A_j} \newcommand{\Aib}{\bar{\A}\local} \newcommand{\AII}{\A_{\I\I}} \newcommand{\AIG}{\A_{\I\G}} \newcommand{\AGI}{\A_{\G\I}} \newcommand{\AGG}{\A_{\G\G}} \newcommand{\AIiIi}{\A_{\Ii\Ii}} \newcommand{\AIiGi}{\A_{\Ii\Gi}} \newcommand{\AGiIi}{\A_{\Gi\Ii}} \newcommand{\AGiGi}{\A_{\Gi\Gi}} \newcommand{\AGiGiw} {{\ensuremath{\A_{\Gi\Gi}^w}}} \newcommand{\AIIi}{\AII\local} \newcommand{\AIGi}{\AIG\local} \newcommand{\AGIi}{\AGI\local} \newcommand{\AGGi}{\AGG\local} \newcommand{\Ab}{\bar{\A}} \newcommand{\Ah}{{\widehat{\A}}} \newcommand{\Aih}{{\Ah\local}} \newcommand{\At}{{\widetilde{\A}}} \newcommand{\Ait}{{\At\local}} \newcommand{\Ao}{\A_0} \newcommand{\Aot}{\At_0} \newcommand{\Aob}{\Ab_0} \newcommand{\AiNN}{\Ai^{(NN)}{}} \newcommand{\AitNN}{\Ait^{(NN)}{}} \newcommand{\AiAS}{\Ai^{(AS)}{}} \newcommand{\AitAS}{\Ait^{(AS)}{}} % Matrix S \renewcommand{\S}{{\cal S}} \newcommand{\Si}{\S\local} \newcommand{\Sb}{\bar{\S}} \newcommand{\Sib}{\Sb\local} \newcommand{\Sh}{{\widehat{\S}}} \newcommand{\Sih}{{\Sh\local}} \newcommand{\St}{{\widetilde{\S}}} \newcommand{\Sit}{{\St\local}} \newcommand{\So}{\S_0} \newcommand{\Soi}{\S_0^i} \newcommand{\Sot}{\St_0} \newcommand{\Sob}{\Sb_0} \newcommand{\SiNN}{\Si^{(NN)}{}} \newcommand{\SitNN}{\Sit^{(NN)}{}} \newcommand{\SiAS}{\Si^{(AS)}{}} \newcommand{\SitAS}{\Sit^{(AS)}{}} % Matrix K \newcommand{\K}{{\cal K}} \newcommand{\Ki}{\K\local} \newcommand{\Kb}{\bar{\K}} \newcommand{\Kib}{\Kb\local} \newcommand{\Kh}{{\widehat{\K}}} \newcommand{\Kih}{{\Kh\local}} \newcommand{\Kt}{{\widetilde{\K}}} \newcommand{\Kit}{{\Kt\local}} \newcommand{\Ko}{\K_0} \newcommand{\Kot}{\Kt_0} \newcommand{\Kob}{\Kb_0} \newcommand{\KiNN}{\Ki^{(NN)}{}} \newcommand{\KitNN}{\Kit^{(NN)}{}} \newcommand{\KiAS}{\Ki^{(AS)}{}} \newcommand{\KitAS}{\Kit^{(AS)}{}} \newcommand{\KII}{\K_{\I\I}} \newcommand{\KIG}{\K_{\I\G}} \newcommand{\KGI}{\K_{\G\I}} \newcommand{\KGG}{\K_{\G\G}} \newcommand{\KIiIi}{\K_{\Ii\Ii}} \newcommand{\KIiGi}{\K_{\Ii\Gi}} \newcommand{\KGiIi}{\K_{\Gi\Ii}} \newcommand{\KGiGi}{\K_{\Gi\Gi}} \newcommand{\KIIi}{\KII\local} \newcommand{\KIGi}{\KIG\local} \newcommand{\KGIi}{\KGI\local} \newcommand{\KGGi}{\KGG\local} \newcommand{\KGiGiw} {{\ensuremath{\K_{\Gi\Gi}^w}}} % Matrix B \newcommand{\B}{{\cal B}} \newcommand{\Bi}{\B\local} \newcommand{\Bib}{\widehat{\B}\local} \newcommand{\Bob}{\widehat{\B}_0} % Matrix C \newcommand{\C}{{\cal C}} % Matrix T \newcommand{\T}{{\cal T}} \newcommand{\Ti}{{\T\local}} % Vectors \newcommand{\uI}{u_\I} \newcommand{\uG}{u_\G} \newcommand{\xI}{x_\I} \newcommand{\xG}{x_\G} \newcommand{\bI}{b_\I} \newcommand{\bG}{b_\G} \newcommand{\fI}{f_\I} \newcommand{\fG}{f_\G} \newcommand{\ftG}{\widetilde f_\G} \newcommand{\ftGi}{\widetilde f_\Gi^{(i)}} \newcommand{\ftGj}{\widetilde f_\Gj^{(j)}} \)

Compose

Table of Contents

See html pages :

1. Overview

Compose (previsouly Maphys++) is a linear algebra C++ library focused on composability. Its purpose is to allow the user to express a large pannel of algorithms using a high-level interface to range from laptop prototypes to many node supercomputer parallel computations.

1.1. Main features

  • Written in C++, C and Fortran interfaces, CMake build system
  • Distributed MPI, hybrid MPI/threads parallelization(threads parallelism is disabled through CMake compilation option by default)
  • Can use Blas/Lapack and Chameleon (matrix products, SPD linear systems, QR/LQ) for dense matrix operations (no MPI version for now, hence limited to one machine node with CPUs and GPUs)
  • Can use MUMPS, PaStiX or qr_mumps as direct sparse solver
  • Can use fabulous as Krylov solver
  • Can use arpack for some preconditioning techniques
  • Matrices forms: general, symmetric, hermitian
  • Sparse storage formats: IJV, CSC, eigen3
  • Precisions: simple, double, complex, double complex

DAG of MaPHyS++ image

2. Download

There are several ways to install MaPHyS++ and its dependencies.

  1. You just want to have a try, to see if it can be installed well on your system, what are the performances on simple cases, run the examples, or simply use the last stable version: we recommand to use one of our packages, .deb ones for those who work on a Linux Debian or Ubuntu distribution, Guix or Spack on other Linux systems, Brew on macOS.
  2. You want to use it but you need a change somewhere in the stack like considering another version (git branch), change the default BLAS/LAPACK or MPI, use your favorite compiler, modify some sources: you may try with Guix or Spack because these package managers allow to build from sources and thus many options can be changed dynamically (command line), or directly build from source with the native build system of the library (Makefile, GNU autotools, CMake) following the procedures described in the installation guide of the library, cf. 5.
  3. You need a tool for reproducibility of your experiments: Guix is recommended.
Git Release source Debian/Ubuntu Brew (Mac) Guix (Linux) Spack (Linux/Mac)
MaPHyS++ releases * brew-repo guix-repo spack-repo
  • We cannot provide a simple debian package because some of MaPHyS++ dependencies do not provide one (blaspp and lapackpp especially). However those are modern packages that can easily be installed, so you should be able to install them manually with instructions given in this section.

3. Dependencies

3.1. Required dependencies

3.1.1. General

  • CMake (version >= 3.12)
  • MPI

3.1.2. Blas/lapack

One of

  • SLATE blaspp and SLATE lapackpp, respectively C++ blas and lapack interfaces (recommanded).
  • <T>LAPACK a blas/lapack C++ header-only implementation, can replace a few blaspp/lapackpp functionnalities for prototyping, but does not guarantee performance. The <T>LAPACK repository is a git submodule of this one.

3.2. Optional dependencies

  • Chameleon (compiled without MPI) dense matrix solver
  • PaStiX (version >= 6.3, compiled with MPI) sparse direct solver (requires SCOTCH >= 7.0.4)
  • Mumps sparse direct solver
  • Arpack-ng (version >= 3.8), necessary for GenEO on sparse matrix, must be compiled with C/C++ interface: ICB flag ON in CMake
  • Paddle (version >= 0.3.5), necessary to work on a centralized input matrix (requires SCOTCH >= 7.0.4)
  • Librsb (version >= 1.3), for optimized sparse matrix computation kernels

    Having at least one direct solver is strongly recommended.

3.3. Additional supported matrices types

3.4. Dependencies for experimental features

  • SZ compressor (for GMRES with compressed basis feature)
  • QRMUMPS (can be used as direct solver for SPD matrices)

4. Documentation

4.1. Literate programming documentation

For advanced users, developers, or people interested in contributing to the code, MaPHyS++ is fully coded in literate programming using emacs's org-mode.

https://solverstack.gitlabpages.inria.fr/maphys/maphyspp/master

4.2. User documentation

No user documentation has been written yet, please refer to the tutorial or the quick start guide.

5. Quick start guide

5.1. Install

5.1.1. Manual installation on linux

  1. Dependencies
    sudo apt-get update -y
    sudo apt-get install -y git cmake build-essential gfortran python wget tar curl pkg-config
    

    For performance, you may also want to install a blas implementation, for instance openblas, and an MPI implementation, for instance openmpi:

    sudo apt-get install -y git openblas openmpi
    

    Then blaspp, lapackpp and arpack-ng can be easily installed from sources (don't forget the ICB flag for arpack-ng to activate the C++ interface):

    # install blaspp, lapackpp and arpack-ng
    git clone https://github.com/icl-utk-edu/blaspp.git
    git clone https://github.com/icl-utk-edu/lapackpp.git
    git clone https://github.com/opencollab/arpack-ng.git
    
    cd blaspp
    mkdir build && cd build
    cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
    make -j3 install
    cd ../..
    
    cd lapackpp
    mkdir build && cd build
    cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
    make -j3 install
    cd ../..
    
    cd arpack-ng
    mkdir build && cd build
    cmake .. -DICB=ON
    make -j3 install
    cd ../..
    

    For Pastix, one can refer to the PaStiX repository, or with CMake:

    git clone --recursive https://gitlab.inria.fr/solverstack/pastix.git
    cd pastix
    cmake -B build -DCMAKE_INSTALL_PREFIX=$PWD/build/install -DBUILD_SHARED_LIBS=ON -DPASTIX_INT64=OFF -DPASTIX_WITH_MPI=ON
    # version with starpu can be enabled with: -DPASTIX_WITH_STARPU=ON
    # if scotch and/or starpu are installed in specific paths add the following to the configuration: -DCMAKE_PREFIX_PATH="path to scotch;path to starpu"
    cmake --build build -j5
    cmake --install build
    

    For Chameleon, one can refer to the Chameleon repository, or with CMake:

    git clone --recursive https://gitlab.inria.fr/solverstack/chameleon.git
    cd chameleon
    cmake -B build -DCHAMELEON_USE_MPI=OFF -DCMAKE_INSTALL_PREFIX=$PWD/build/install -DBUILD_SHARED_LIBS=ON
    # if starpu is installed in a specific path add the following to the configuration: -DCMAKE_PREFIX_PATH="path to starpu"
    cmake --build build -j5
    cmake --install build
    
  2. MaPHyS++

    Get MaPHys++'s sources (don't forget to get the git submodules !)

    # if git version >= 1.9
    git clone --recursive https://gitlab.inria.fr/solverstack/maphys/maphyspp.git
    cd maphyspp
    # else
    git clone --recursive git@gitlab.inria.fr:solverstack/maphys/maphyspp.git
    cd maphyspp
    git submodule init
    git submodule update
    

    Then MaPHyS++ uses standard CMake installation. From the sources root directory:

    mkdir build && cd build
    cmake .. -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=/path/to/install # and other cmake flags needed
    make install
    

    Check CMakeLists.txt to see which CMake flags you want to use for your installation.

5.1.2. With guix

We use guix for reproducible research purposes. Here is the current configuration used for MaPHyS++.

MaPHyS++ is distributed through guix in the guix-hpc repository.

The channel configuration (usually in ~/.config/guix/channels.scm if not configured differently):

(cons (channel
        (name 'guix-hpc-non-free)
        (url "https://gitlab.inria.fr/guix-hpc/guix-hpc-non-free.git"))
      %default-channels)

To launch a bash in a MaPHyS++ environment, for users:

guix shell --pure maphys++ -- /bin/bash --norc

For developers, you can add some debugging packages, and emacs to tangle and export from the org sources. For example:

guix shell --pure -D maphys++ eigen emacs emacs-org gdb valgrind -- /bin/bash --norc

To run tests, you might need to set the openmpi variable as follows (to allow more processes to run than you have physical CPU cores on your computer):

export OMPI_MCA_rmaps_base_oversubscribe=1

5.1.3. With spack

Spack packages for Linux or macOS are stored in our spack-repo git repository. Please refer to the README for installation instructions.

Examples:

# please read https://spack.readthedocs.io/en/latest/getting_started.html
git clone https://github.com/llnl/spack.git
cd spack
git checkout v0.16.2
. share/spack/setup-env.sh
# Currently spack provides openmpi v3 as default openmpi. Add the
# following in your etc/spack/defaults/packages.yaml in order to set
# openmpi 4.0.5 to be the default:
# openmpi:
#   version: [4.0.5]
git clone https://gitlab.inria.fr/solverstack/spack-repo.git
spack repo add spack-repo
spack install maphyspp
# maphyspp is installed here:
spack location -i maphyspp

Spack allows to expose many build variants so that it is difficult to ensure that all installations will succeed.

5.1.4. With brew (MacOS)

Brew packages for macOS are stored in our brew-repo git repository. Please refer to the README for installation instructions. Examples:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
git clone https://gitlab.inria.fr/solverstack/brew-repo.git
cd brew/repo
brew install --build-from-source blaspp.rb lapackpp.rb fabulous.rb pastix.rb maphyspp.rb

5.2. Linking

If you build your project with CMake we provide a maphysppConfig.cmake file at installation, in the subdirectory lib/cmake/maphyspp/ of the installation. Example of CMakeLists.txt for MaPHyS++, where your code is in mpp_example.cpp:

cmake_minimum_required(VERSION 3.12)

project(MAPHYS_EXAMPLE CXX C Fortran)

find_package(maphyspp REQUIRED)

# compile your example
add_executable(mpp_example mpp_example.cpp)

# link to maphyspp
target_link_libraries(mpp_example PRIVATE MAPHYSPP::maphyspp)

5.3. Using

See the tutorial section for a progressive tutorial into MaPHyS++.

6. Tutorial

7. Benchmarks

8. Publications

9. Contact

  • Emmanual Agullo
  • Luc Giraud
  • Gilles Marait

10. Acknowledgment

This software effort has been partially funded by Inria ADT and the EoCoE-2 european project.

11. See also

12. LICENSE

Date: 18/01/2024 at 18:51:47

Author: HiePACS

Created: 2024-01-18 Thu 18:51

Validate