solverstack
maphys
maphyspp

Repository



Compose
See html pages :

  html version
  literate programming documentation
  
development branches (private access for developers)

Overview
<sec:overview>
MaPHyS++ is a linear algebra package developed in C++. Its main purpose is the
  solution of sparse linear system $$\K u = f$$ where $\K$ is a square real or
  complex non singular general matrix, $f$ is a given right-hand side vector, and
  $x$ is the solution vector to be computed.
MaPHyS++ provides a set of direct and iterative linear solvers that can be
  combined to solve directly $\K u = f$ or use an hybrid approach. It follows a
  non-overlapping algebraic domain decomposition method that first reorders the
  linear system into a $2 × 2$ block system
\begin{equation}
  \left(
  \begin{array}{cc}
  \KII & \KIG 

  \KGI & \KGG \
  \end{array}
  \right)
  \left( \begin{array}{c} \xI \ \xG \ \end{array} \right) =
  \left( \begin{array}{c} \fI \ \fG \ \end{array} \right),
  \end{equation}
  where $\KII$ and $\KGG$ respectively represent interior
  subdomains and separators, and $\KIG$ and $\KGI$ are the
  coupling between interior and separators. By eliminating the unknowns associated
  with the interior subdomains $\KII$ we get
\begin{equation}
  \left(
  \begin{array}{cc}
  \KII & \KIG 

  0 & \S \
  \end{array}
  \right)
  \left( \begin{array}{c} \xI \ \xG \ \end{array} \right) =
  \left( \begin{array}{c} \fI \ \ftG \ \end{array} \right),
  \end{equation}
  with
  \begin{equation}
  \S=\KGG-\KGI \KII\inv \KIG
  \; \textrm{ and} \;
  \ftG = f_Γ -\KGI \KII\inv \fI.
  \end{equation}
The matrix $\S$ is referred to as the Schur complement matrix. Because
  most of the fill-in appears in the Schur complement, the Schur complement system
  is solved using a preconditioned Krylov subspace method while the interior
  subdomain systems are solved using a sparse direct solver. Although, the Schur
  complement system is significantly better conditioned than the original matrix
  $\K$, it is important to consider further preconditioning when employing a
  Krylov method.
Main features

  Written in C++, C and Fortran interfaces, CMake build system
  Distributed MPI, hybrid MPI/threads parallelization
  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
  Storage formats: IJV, armadillo, eigen3
  Precisions: simple, double, complex, double complex


News
<sec:news>
[03/11/21] Release 1.1
See https://gitlab.inria.fr/solverstack/maphys/maphyspp/-/releases/v1.1.3
[08/07/21] Release 1.0
See https://gitlab.inria.fr/solverstack/maphys/maphyspp/-/releases/v1.0.0
Download
<sec: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. sec:quickstart.
  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++
1.1.3
*
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.

Dependencies
<sec:dependencies>
Required dependencies

  CMake (version >= 3.12)
  
SLATE blaspp, a C++ BLAS interface.
  
SLATE lapackpp, a C++ lapack interface.
  MPI

Optional dependencies

  
PaStiX (direct solver, compiled with MPI)
  
Mumps (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
    Having at least one direct solver is strongly recommended.
  

Additional supported matrices types

  
Eigen (not fully tested)

Dependencies for experimental features

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

Documentation
<sec:documentation>
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
User documentation
No user documentation has been written yet, please refer to the tutorial or
  the quick start guide.
Quick start guide
<sec:quickstart>
Install
Manual installation on linux
<subsec:manual_install>
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://bitbucket.org/icl/blaspp.git
git clone https://bitbucket.org/icl/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 use the debian package:
# install pastix
curl https://gitlab.inria.fr/solverstack/pastix/-/package_files/26294/download -o pastix_6.2.1-1_amd64.deb
apt-get install -y ./pastix_6.2.1-1_amd64.deb

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.
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):
(list (channel
       (name 'guix)
       (url "https://git.savannah.gnu.org/git/guix.git")
       (commit
        "ffc04f5cc6df16b5c10746ce7e4ef44fafc626e6"))
      (channel
       (name 'guix-hpc-non-free)
       (url "https://gitlab.inria.fr/guix-hpc/guix-hpc-non-free.git")
       (commit
        "c23b477f88f691aac93d1aeb647e4f0e501d19a4"))
      (channel
       (name 'guix-hpc)
       (url "https://gitlab.inria.fr/guix-hpc/guix-hpc.git")
       (commit
        "c89c78b77b50a41bda2577ba883e465ab57313c2")))

To launch a bash in a MaPHyS++ environment, for users:
guix environment --pure maphys++ --ad-hoc eigen -- /bin/bash --norc

For developers, you can add some debugging packages, and emacs to tangle and export from the org sources. I suggest:
guix environment --pure maphys++ --ad-hoc 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

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.
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

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)

Using
See the tutorial section for a progressive tutorial into MaPHyS++.
Tutorial
<sec:tutorial>
See https://solverstack.gitlabpages.inria.fr/maphys/maphyspp/master/tutorial/tuto.html
Benchmarks
<sec:benchmarks>
See https://solverstack.gitlabpages.inria.fr/maphys/maphyspp/master/bench/weekly_results.html
Publications
<sec:publications>
Contact
<sec:contacts>

  Emmanual Agullo
  Luc Giraud
  Gilles Marait

Acknowledgment
<sec:acknowledgments>
This software effort has been partially funded by Inria ADT and the EoCoE-2 european project.
See also

  Original MaPHyS fortran repository

  Louis Poirel’s PhD thesis : Algebraic domain decomposition methods for hybrid (iterative/direct) solvers


LICENSE
https://gitlab.inria.fr/solverstack/maphys/maphyspp/-/blob/master/LICENSE