\( \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

1. General overview

See the pdf version. See other branches version.

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 \(u\) 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 \times 2\) block system

\begin{equation} \left( \begin{array}{cc} \KII & \KIG \\ \KGI & \KGG \\ \end{array} \right) \left( \begin{array}{c} \uI \\ \uG \\ \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} \uI \\ \uG \\ \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_\Gamma -\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.

See tutorial for more information on how to use the library.

2. The MaPHyS++ library

2.1. Introduction

MaPHyS++ provides its own basic linear algebra datatypes for matrices, vector, … It is also possible to use external datatypes with MaPHyS++ tools.

2.2. Namespace

The C++ namespace used by MaPHys++ is maphys.

using namespace maphys;

2.3. Scalar types

In the rest of the documentation, we refer to Scalar for the following C++ types:

  • float: single precision (32 bits) real;
  • double: double precision (64 bits) real;
  • std::complex<float>: single precision (64 bits) complex;
  • std::complex<double>: double precision (128 bits) complex.

Those are the types supported by MaPHyS++ datatypes, in other words the types of data that can be stored in a vector or a matrix.

We may also refer to Real as the real type associated to the Scalar type. It is for example the type you should use for a norm or a tolerance criterion for an iterative method. For real types (float and double), Scalar and Real are the same, but not for complex types. For instance, the Real type associated to std::complex<float> is float.

In MaPHyS++, one can access the Real type associated to a Scalar as follows:

using Real = typename maphys::arithmetic_real<Scalar>::type;

See Arithmetic for more details.

3. Coding tools

3.1. Arithmetics

3.2. Error management

3.3. Cross product iterator

3.4. Macros

3.5. SZ compressor wrapper

4. Matrix interface

4.1. Basic concepts

4.2. Linear algebra concepts

4.3. Common traits and definitions

4.4. Eigen wrapper

4.5. Eigen dense solver

4.6. Eigen sparse solver

4.7. Armadillo wrapper

5. Datatypes

5.1. Matrix properties

5.2. Arrays

5.3. Dense vectors and matrices

5.3.1. Dense data

5.3.2. Dense matrix

5.3.3. Expression templates

5.4. Diagonal matrices

5.5. Sparse matrices

5.5.1. Base sparse matrix class

5.5.2. Sparse matrix COO

5.5.3. Sparse matrix CSC

5.5.4. Sparse matrix LIL

5.6. Partitioned vectors and matrices

5.6.1. Partitioned base class

5.6.2. Partitioned operator

5.6.3. Partitioned vector

5.6.4. Partitioned matrix

6. Distributed framework

6.1. MPI

MPI

6.2. Process

6.3. Subdomain

7. Solvers

7.1. Linear operator interface

7.2. Iterative solvers

7.2.1. Generic interface

7.2.2. Generic tests

7.2.3. Jacobi

7.2.4. Conjugate gradient

7.2.5. GCR

GCR

7.2.6. BiCGSTAB

7.2.7. GMRES

7.2.8. Fabulous

7.3. Direct solvers

7.3.1. BLAS / LAPACK

7.3.2. Pastix

7.3.3. Mumps

7.3.4. Qr-Mumps

7.4. Hybrid solvers

7.4.1. Schur complement solver

7.4.2. Partitioned Schur complement solver

7.4.3. Implicit Schur operator

7.5. Centralized solver

7.6. Coarse solver

8. Preconditioners

8.1. Diagonal preconditioner

8.2. Abstract Schwarz

8.3. Two level abstract Schwarz

8.4. Eigen-deflated preconditioner

9. I/O

9.1. Matrix market loader

9.2. Domain decomposition

10. Linear algebra tools

10.1. Induced matrix norm

10.2. Arpack eigen solver

11. Kernels

11.1. Blas/lapack kernels

11.2. Tlapack kernels

11.3. Sparse kernels

12. Graph and partitioning

12.1. Paddle

13. Unit test matrices

13.1. Test matrices

14. Benchmark results

Date: 18/01/2024 at 18:49:32

Author: HiePACS

Created: 2024-01-18 Thu 18:49

Validate