README.md 8.81 KB
Newer Older
RAMET Pierre's avatar
RAMET Pierre committed
1
# PaStiX: A sparse direct solver
Mathieu Faverge's avatar
Mathieu Faverge committed
2

3
[![pipeline status](https://gitlab.inria.fr/solverstack/pastix/badges/master/pipeline.svg)](https://gitlab.inria.fr/solverstack/pastix/pipelines) [![coverage report](https://gitlab.inria.fr/solverstack/pastix/badges/master/coverage.svg)](https://sonarqube.inria.fr/sonarqube/dashboard?id=hiepacs%3Apastix%3Agitlab%3Amaster)[![coverity report](https://scan.coverity.com/projects/20282/badge.svg)](https://scan.coverity.com/projects/pastix)
Mathieu Faverge's avatar
Mathieu Faverge committed
4

Mathieu Faverge's avatar
Mathieu Faverge committed
5
PaStiX (Parallel Sparse matriX package) is a scientific library that provides a
Mathieu Faverge's avatar
Mathieu Faverge committed
6 7 8
high performance parallel solver for very large sparse linear systems based on
direct methods.  Numerical algorithms are implemented in single or double
precision (real or complex) using LLt, LDLt and LU with static pivoting (for non
RAMET Pierre's avatar
RAMET Pierre committed
9 10
symmetric matrices having a symmetric pattern).
This solver also provides some low-rank compression methods to reduce the memory footprint and/or the time-to-solution.
Mathieu Faverge's avatar
Mathieu Faverge committed
11

RAMET Pierre's avatar
RAMET Pierre committed
12
## Get PaStiX
Mathieu Faverge's avatar
Mathieu Faverge committed
13 14

To use last development state of PaStiX, please clone the master
RAMET Pierre's avatar
RAMET Pierre committed
15
branch. Note that PaStiX contains two `git submodule` for **spm** and **morse_cmake**.
Mathieu Faverge's avatar
Mathieu Faverge committed
16 17 18 19 20 21 22 23 24 25 26
To get sources please use these commands:

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

27
Previous releases of PaStiX are hosted on the
RAMET Pierre's avatar
RAMET Pierre committed
28
[gforge.inria.fr](https://gforge.inria.fr/frs/?group_id=186) for now.
Mathieu Faverge's avatar
Mathieu Faverge committed
29 30
Future releases will be available on this gitlab project.

RAMET Pierre's avatar
RAMET Pierre committed
31
## Available Features
Mathieu Faverge's avatar
Mathieu Faverge committed
32

33
* Features available in shared memory with POSIX threads for multicores architectures.
Mathieu Faverge's avatar
Mathieu Faverge committed
34

35 36 37 38 39 40 41 42 43 44 45
|                         | Seq   | Static | Dyn   | StarPU    | PaRSEC    |
|-------------------------|-------|--------|-------|-----------|-----------|
| POTRF (Cholesky)        | FR/LR | FR/LR  | FR/LR | FR/LR/GPU | FR/LR/GPU |
| PXTRF (LL^t for complex)| FR/LR | FR/LR  | FR/LR | FR/LR/GPU | FR/LR/GPU |
| HETRF (LDL^h)           | FR/LR | FR/LR  | FR/LR | FR/LR/GPU | FR/LR/GPU |
| SYTRF (LDL^t)           | FR/LR | FR/LR  | FR/LR | FR/LR/GPU | FR/LR/GPU |
| GETRF (LU)              | FR/LR | FR/LR  | FR/LR | FR/LR/GPU | FR/LR/GPU |
| TRSM                    | FR/LR | FR/LR  | FR/LR | FR/LR     | -         |
| DIAG                    | FR/LR | FR/LR  | FR/LR | FR/LR     | -         |

* Features available in hybrid shared/distributed memory with MPI between processes, and POSIX threads within a process.
Mathieu Faverge's avatar
Mathieu Faverge committed
46

47 48 49 50 51 52 53 54 55 56 57 58
|                         | Seq   | Static | Dyn   | StarPU    | PaRSEC    |
|-------------------------|-------|--------|-------|-----------|-----------|
| POTRF (Cholesky)        | FR    | FR     | FR    | FR/GPU    | FR/GPU    |
| PXTRF (LL^t for complex)| FR    | FR     | FR    | FR/GPU    | FR/GPU    |
| HETRF (LDL^h)           | FR    | FR     | FR    | FR/GPU    | FR/GPU    |
| SYTRF (LDL^t)           | FR    | FR     | FR    | FR/GPU    | FR/GPU    |
| GETRF (LU)              | FR    | FR     | FR    | FR/GPU    | FR/GPU    |
| TRSM                    | FR    | FR     | FR    | FR        | -         |
| DIAG                    | FR    | FR     | FR    | FR        | -         |

* FR means Full-Rank computations without compression techniques
* LR means Low-Rank compression technique to reduce the memory footprint and/or the time-to-solution
RAMET Pierre's avatar
RAMET Pierre committed
59
* *WARNING* GPU kernels are not available on compressed supernodes
60
* *WARNING* Low-rank compression and Schur complement are not available with MPI yet.
RAMET Pierre's avatar
RAMET Pierre committed
61

RAMET Pierre's avatar
RAMET Pierre committed
62
## Documentation
Mathieu Faverge's avatar
Mathieu Faverge committed
63

Mathieu Faverge's avatar
Mathieu Faverge committed
64
The latest Doxygen documentation is available [here](http://solverstack.gitlabpages.inria.fr/pastix).
65

66
The [main steps](http://solverstack.gitlabpages.inria.fr/pastix/group__pastix__users.html) and [parameters](http://solverstack.gitlabpages.inria.fr/pastix/group__pastix__api.html) of the solver are described. Some [examples](http://solverstack.gitlabpages.inria.fr/pastix/group__pastix__examples.html) are also provided.
Mathieu Faverge's avatar
Mathieu Faverge committed
67

RAMET Pierre's avatar
RAMET Pierre committed
68
## Installation
Mathieu Faverge's avatar
Mathieu Faverge committed
69 70 71 72 73

### Build and install with CMake

PaStiX can be built using [CMake](https://cmake.org/). This
installation requires to have some library dependencies already
Pierre Ramet's avatar
Pierre Ramet committed
74
installed on the system:
RAMET Pierre's avatar
RAMET Pierre committed
75 76 77 78 79 80 81 82 83 84 85

* BLAS (MKL, OpenBlas, ...) and CBLAS (sequential version required)
* LAPACK and LAPACKE (sequential version required, with TMG enabled for testing)
* HWLOC (highly recommended)
* SCOTCH (optional)
* METIS (optional)
* STARPU runtime support (optional)
* PARSEC runtime support (optional)
* CUDA/CuBLAS to enable GPU functionality with runtime support (optional)
* EZTRACE to enable tracing support (optional)
* Python and Fortran compiler for wrappers and examples (optional)
Mathieu Faverge's avatar
Mathieu Faverge committed
86

Pierre Ramet's avatar
Pierre Ramet committed
87 88
For instance, on debian-like systems, dependencies can be installed with the following command:

RAMET Pierre's avatar
RAMET Pierre committed
89
      sudo apt-get install cmake gcc gfortran libhwloc-dev libscotch-dev libopenblas-dev liblapacke-dev python-numpy
Pierre Ramet's avatar
Pierre Ramet committed
90

Mathieu Faverge's avatar
Mathieu Faverge committed
91
The main options to configure the PaStiX configuration build are:
RAMET Pierre's avatar
RAMET Pierre committed
92 93 94 95 96 97 98 99 100 101 102 103 104

* Classic cmake options:
  * CMAKE_BUILD_TYPE: Debug, RelWithDebInfo, Release, MinSizeRel; we recommend to use the Release, or RelWithDebInfo, for performance.
  * CMAKE_INSTALL_PREFIX: Specify the prefix directory to install the library
  * BUILD_SHARED_LIBS=[OFF]: Enable the shared libraries build. This option needs to be enabled for the Python wrapper.
* Integer type:
  * PASTIX_INT64[=ON]: Enable/disable int64_t for integer arrays.
* Ordering libraries:
  * Ordering libraries must match the integer type chosen for integer arrays in PaStiX
  * PASTIX_ORDERING_SCOTCH[=ON]: Enable/Disable the support of the Scotch library to compute the ordering.
  * PASTIX_ORDERING_METIS[=OFF]: Enable/Disable the support of the Metis library to compute the ordering. Metis 5.1 is required.
* External schedulers:
  * PASTIX_WITH_PARSEC[=OFF]: Enable/disable the PaRSEC runtime support. Require to install PaRSEC tag pastix-_releasenumber_ (mymaster for master branch) from the repository <https://bitbucket.org/mfaverge/parsec> that includes a few patches on top of the original PaRSEC runtime system. PaRSEC needs to be compiled with option -DPARSEC_WITH_DEVEL_HEADERS=ON.
Mathieu Faverge's avatar
Mathieu Faverge committed
105
  * PASTIX_WITH_STARPU[=OFF]: Enable/disable the StarPU runtime support. Require to install StarPU 1.3.
RAMET Pierre's avatar
RAMET Pierre committed
106
* Distributed memory:
Mathieu Faverge's avatar
Mathieu Faverge committed
107 108 109
  * PASTIX_WITH_MPI=[OFF]: Enable/disable distributed memory support (See above for details). If used with the PaRSEC library, MPI should be enabled or disabled in both libraries.*
* External SpM library:
  * PASTIX_WITH_EXTERNAL_SPM=[OFF]: Enable/disable the use of an external SpM library in favor of the internal one.
RAMET Pierre's avatar
RAMET Pierre committed
110 111 112 113
* Documentation:
  * BUILD_DOCUMENTATION[=OFF] to enable the Doxygen documentation generation.

## Get involved
Mathieu Faverge's avatar
Mathieu Faverge committed
114

Mathieu Faverge's avatar
Mathieu Faverge committed
115
### Reporting an issue
Mathieu Faverge's avatar
Mathieu Faverge committed
116

Mathieu Faverge's avatar
Mathieu Faverge committed
117
We strongly recommend all users to use the issue tracker to report any problems with the software, or for any feature request. We will try our best to answer them in a short time frame.
Mathieu Faverge's avatar
Mathieu Faverge committed
118 119 120

### Contributions

RAMET Pierre's avatar
RAMET Pierre committed
121
<https://gitlab.inria.fr/solverstack/pastix/blob/master/CONTRIBUTING.md>
Mathieu Faverge's avatar
Mathieu Faverge committed
122

RAMET Pierre's avatar
RAMET Pierre committed
123
## Authors
Mathieu Faverge's avatar
Mathieu Faverge committed
124 125

The following people contribute or contributed to the development of PaStiX:
RAMET Pierre's avatar
RAMET Pierre committed
126 127 128 129 130 131 132 133 134 135 136

* Mathieu Faverge, PI
* Pierre Ramet, PI
* David Goudin
* Mathias Hastaran
* Pascal Henon
* Xavier Lacoste
* François Pellegrini
* Grégoire Pichon, Low-rank solver
* Florent Pruvost, CMake and Spack
* Theophile Terraz
137
* Tony Delarue, MPI implementation
Mathieu Faverge's avatar
Mathieu Faverge committed
138 139 140

If we forgot your name, please let us know that we can fix that mistake.

RAMET Pierre's avatar
RAMET Pierre committed
141
## Citing PaStiX
Mathieu Faverge's avatar
Mathieu Faverge committed
142

Pierre Ramet's avatar
Pierre Ramet committed
143 144 145
Feel free to use the following publications to reference PaStiX:

* Original paper that initiated PaStiX:
RAMET Pierre's avatar
RAMET Pierre committed
146
  * Pascal Hénon, Pierre Ramet, Jean Roman. Pascal Hénon, Pierre Ramet, Jean Roman. PaStiX: A High-Performance Parallel Direct Solver for Sparse Symmetric Definite Systems. Parallel Computing, Elsevier, 2002, 28 (2), pp.301--321. [INRIA HAL](https://hal.inria.fr/inria-00346017)
Pierre Ramet's avatar
Pierre Ramet committed
147
* Parallel incomplete factorization implemented in PaStiX:
RAMET Pierre's avatar
RAMET Pierre committed
148
  * Pascal Hénon, Pierre Ramet, Jean Roman. On finding approximate supernodes for an efficient ILU(k) factorization. Parallel Computing, Elsevier, 2008, 34, pp.345--362. [INRIA HAL](https://hal.inria.fr/inria-00346018)
Pierre Ramet's avatar
Pierre Ramet committed
149
* Reordering strategy for blocking optimization in PaStiX:
RAMET Pierre's avatar
RAMET Pierre committed
150
  * Grégoire Pichon, Mathieu Faverge, Pierre Ramet, Jean Roman. Reordering Strategy for Blocking Optimization in Sparse Linear Solvers. SIAM Journal on Matrix Analysis and Applications, Society for Industrial and Applied Mathematics, 2017, SIAM Journal on Matrix Analysis and Applications, 38 (1), pp.226 - 248. [INRIA HAL](https://hal.inria.fr/hal-01485507v2)
Pierre Ramet's avatar
Pierre Ramet committed
151
* On the use of low rank approximations in PaStiX:
Mathieu Faverge's avatar
Mathieu Faverge committed
152
  * Grégoire Pichon, Eric Darve, Mathieu Faverge, Pierre Ramet, Jean Roman. Sparse supernodal solver using block low-rank compression: Design, performance and analysis. International Journal of Computational Science and Engineering, Inderscience, 2018, 27, pp.255 - 270. [10.1016/J.JOCS.2018.06.007](http://dx.doi.org/10.1016/J.JOCS.2018.06.007) [Inria HAL](https://hal.inria.fr/hal-01824275)
Mathieu Faverge's avatar
Mathieu Faverge committed
153

RAMET Pierre's avatar
RAMET Pierre committed
154
## Licence
Mathieu Faverge's avatar
Mathieu Faverge committed
155

156
<https://gitlab.inria.fr/solverstack/pastix/blob/master/LICENSE>