|
1 | | -# HTOOL [](https://github.com/htool-ddm/htool/actions/workflows/CI.yml) [](https://codecov.io/gh/htool-ddm/htool) |
| 1 | +# Htool-DDM [](https://github.com/htool-ddm/htool/actions/workflows/CI.yml) [](https://codecov.io/gh/htool-ddm/htool) [](http://htool-ddm.pages.math.cnrs.fr/) |
2 | 2 |
|
3 | | -## What is Htool? |
| 3 | +**Htool-DDM** is a lightweight header-only C++14 library that provides an easy-to-use interface for parallel iterative solvers and a default matrix compression via in-house hierarchical matrix implementation. Its goal is to provide modern iterative solvers for dense/compressed linear systems. |
4 | 4 |
|
5 | | -Htool is an implementation of hierarchical matrices (cf. this [reference](http://www.springer.com/gp/book/9783662473238) or this [one](http://www.springer.com/gp/book/9783540771463)), it was written to test Domain Decomposition Methods (DDM) applied to Boundary Element Method (BEM). It provides: |
| 5 | +It is also an extensible framework which contains several customization points. For example, one can provide its own compression algorithm, or customize the default hierarchical compression. Via its interface with [HPDDM](https://github.com/hpddm/hpddm), it is also a flexible tool to test various iterative solvers and preconditioners. |
6 | 6 |
|
7 | | -* routines to build hierarchical matrix structures (cluster trees, block trees, low-rank matrices and block matrices), |
8 | | -* parallel matrix-vector and matrix-matrix product using MPI and OpenMP, |
9 | | -* preconditioning techniques using domain decomposition methods, |
10 | | -* the possibility to use Htool with any generator of coefficients (e.g., your own BEM library), |
11 | | -* an interface with [HPDDM](https://github.com/hpddm/hpddm) for iterative solvers, |
12 | | -* and several utility functions to display information about matrix structures and timing. |
13 | | - |
14 | | -It is now used in [FreeFEM](https://freefem.org) starting from version 4.5, and we developed a [Python interface](https://github.com/htool-ddm/htool_python) using `pybind11`. |
15 | | - |
16 | | -## How to use Htool? |
17 | | - |
18 | | -### Dependencies |
19 | | - |
20 | | -Htool is a header-only library written in C++11 with MPI and OpenMP, but it can be used without the latter if needed. Then, to use Htool, it requires: |
21 | | - |
22 | | -* BLAS, to perform algebraic operations (dense matrix-matrix or matrix-vector operations). |
23 | | - |
24 | | -And if you want, it needs: |
25 | | - |
26 | | -* LAPACK, to perform SVD compression, |
27 | | -* HPDDM and its dependencies (BLAS, LAPACK) to use iterative solvers and DDM preconditioners. |
28 | | - |
29 | | - |
30 | | -### Installing |
31 | | - |
32 | | -Since Htool is a header-only library, you can just include in your code the `include` folder of this repository. You can also use the following command to install the `include` folder in the one of your system to make it more widely available: in the root of this repository on your system, you can do: |
33 | | - |
34 | | -```bash |
35 | | -mkdir build |
36 | | -cd build |
37 | | -cmake .. |
38 | | -cmake --build . --config Release --target install -- -j $(nproc) |
39 | | -``` |
40 | | - |
41 | | -Note that you can modify the `install` prefix using `cmake .. -DCMAKE_INSTALL_PREFIX:PATH=your/install/path` instead of the third line. |
42 | | - |
43 | | -### Embedding Htool in your code |
44 | | - |
45 | | -We mostly refer to `smallest_example.cpp` and `smallest_example.py` in the `examples` folder to see how to use Htool. |
46 | | - |
47 | | -A function that generates the coefficients must be provided to Htool. To do so, a structure inheriting from `IMatrix<T>` must be defined with a method called `T get_coef(const int& i, const int& j) const`, where `T` is the type of your coefficients. This method will return the coefficient (i,j) of the considered problem. A method `get_submatrix` can also be defined to provide a more efficient way to build a sub-block of the matrix. An example of such interface is given in `test_hmat_partialACA.hpp` or [BemTool](https://github.com/xclaeys/BemTool) (see `bemtool/miscellaneous/htool_wrap.hpp`). This new structure and the geometry will be used to define an object `HMatrix`. |
48 | | - |
49 | | -A new type of compressor can also be added by defining a structure inheriting from `LowRankMatrix` with a method called `build` which populates the data members needed (see `partialACA.hpp`). |
50 | | - |
51 | | -### Python interface |
52 | | - |
53 | | -See this [repository](https://github.com/htool-ddm/htool_python). |
54 | | - |
55 | | -## Who is behind Htool? |
56 | | - |
57 | | -If you need help or have questions regarding Htool, feel free to contact [Pierre Marchand](https://www.ljll.math.upmc.fr/marchandp/) and Pierre-Henri Tournier. |
58 | | - |
59 | | -## Acknowledgements |
60 | | - |
61 | | -[University of Bath](https://www.bath.ac.uk), United Kingdom |
62 | | -[ANR NonlocalDD](https://www.ljll.math.upmc.fr/~claeys/nonlocaldd/index.html), (grant ANR-15-CE23-0017-01), France |
63 | | -[Inria](http://www.inria.fr/en/) Paris, France |
64 | | -[Laboratoire Jacques-Louis Lions](https://www.ljll.math.upmc.fr/en/) Paris, France |
65 | | - |
66 | | -## Collaborators/contributors |
67 | | - |
68 | | -[Matthieu Ancellin](https://ancell.in) |
69 | | -[Xavier Claeys](https://www.ljll.math.upmc.fr/~claeys/) |
70 | | -[Pierre Jolivet](http://jolivet.perso.enseeiht.fr/) |
71 | | -[Frédéric Nataf](https://www.ljll.math.upmc.fr/nataf/) |
72 | | - |
73 | | - |
| 7 | +See [documentation](http://htool-ddm.pages.math.cnrs.fr/) for more information. |
0 commit comments