Compose
Table of Contents
See html pages :
- html version
- literate programming documentation
- development branches (private access for developers)
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
2. Download
There are several ways to install MaPHyS++
and its dependencies.
- 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.
- 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.
- 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
andlapackpp
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.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
- 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 instanceopenmpi
:sudo apt-get install -y git openblas openmpi
Then
blaspp
,lapackpp
andarpack-ng
can be easily installed from sources (don't forget theICB
flag forarpack-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
- 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++
.
7. Benchmarks
10. Acknowledgment
This software effort has been partially funded by Inria ADT and the EoCoE-2 european project.
11. See also
- Original MaPHyS fortran repository
- Louis Poirel's PhD thesis : Algebraic domain decomposition methods for hybrid (iterative/direct) solvers