README.md 4.54 KB
Newer Older
1 2
# ScalFMM: Fast Multipole Method

PRUVOST Florent's avatar
PRUVOST Florent committed
3 4 5
[![pipeline status](https://gitlab.inria.fr/solverstack/ScalFMM/badges/develop/pipeline.svg)](https://gitlab.inria.fr/solverstack/ScalFMM/commits/develop)
[![coverage report](https://gitlab.inria.fr/solverstack/ScalFMM/badges/develop/coverage.svg)](https://gitlab.inria.fr/solverstack/ScalFMM/commits/develop)

6 7 8 9 10 11 12 13 14 15 16
----

:warning: ScalFMM has moved to Inria's GitLab: https://gitlab.inria.fr/solverstack/ScalFMM

----

**ScalFMM** is a C++ library that implements a kernel independent Fast Multipole Method.


Copyright Inria, please read the licence.

ESTERIE Pierre's avatar
ESTERIE Pierre committed
17
## Requirements
18

ESTERIE Pierre's avatar
ESTERIE Pierre committed
19
  - CMake v3.10.0 or later
20 21 22 23 24 25 26 27 28 29 30
  - C++ compiler that supports
    - C++14 [compiler support list](http://en.cppreference.com/w/cpp/compiler_support)
    - [OpenMP](http://www.openmp.org/resources/openmp-compilers/)

The following are optional:

  - [Doxygen](http://www.stack.nl/~dimitri/doxygen/) to build the documentation.
  - An MPI implementation to build the distributed files.
  - Custom BLAS, FFT implementations.
  - [StarPU](http://starpu.gforge.inria.fr/) for the relevant FMM implementations.

ESTERIE Pierre's avatar
ESTERIE Pierre committed
31 32 33 34 35
## Get and Build ScalFMM

### Cloning

To use last development states of ScalFMM, please clone the master
Berenger Bramas's avatar
Berenger Bramas committed
36
  branch. Note that ScalFMM contains two git submodules `morse_cmake` and `inastemp`.
37
  To get sources please use these commands:
38
``` bash
ESTERIE Pierre's avatar
ESTERIE Pierre committed
39
git clone --recursive git@gitlab.inria.fr:solverstack/ScalFMM.git -b requested_branch
40
```
COULAUD Olivier's avatar
COULAUD Olivier committed
41 42 43 44 45 46 47 48
or
```bash
git clone git@gitlab.inria.fr:solverstack/ScalFMM.git
cd ScalFMM
git submodule init
git submodule update

``` 
ESTERIE Pierre's avatar
ESTERIE Pierre committed
49 50 51 52
### Building
You can do an out-of-source build by creating a `build` folder out of your clone or you can use the `Build`
folder inside your clone.

COULAUD Olivier's avatar
COULAUD Olivier committed
53
``` bash
54 55 56 57 58 59 60 61 62
cd scalfmm/Build
# Use cmake, with relevant options
cmake .. # -DSCALFMM_USE_MPI=ON
```

The build may be configured after the first CMake invocation using, for instance, `ccmake` or `cmake-gui`.

```bash
# Still in the Build folder
63
ccmake ../
64
# Or
65
cmake-gui ../
66 67
```

ESTERIE Pierre's avatar
ESTERIE Pierre committed
68 69 70 71 72 73 74
The binaries are then compiled calling `make` (or `ninja` if you specified it at the configure step).
They can be found in `scalfmm/Build/Tests/{Release,Debug}/...`

Invoke `make help` to see the available targets.
Gloabal targets are available :
* `scalfmm_examples` builds the examples in the `Example` folder,
* `scalfmm_utests` builds the unit tests in the `Utests` folder.
75 76 77 78

An example build using StarPU:

```bash
ESTERIE Pierre's avatar
ESTERIE Pierre committed
79 80
cmake .. -DSCALFMM_USE_BLAS=ON -DSCALFMM_USE_MKL_AS_BLAS=ON -DSCALFMM_USE_FFT=ON -DSCALFMM_USE_STARPU=ON
make all
81 82
```

ESTERIE Pierre's avatar
ESTERIE Pierre committed
83 84 85 86
You can also specify your install directory with `-DCMAKE_INSTALL_PREFIX=/path/to/your/install` and then
call `make install`

## Using ScalFMM in your project
87

ESTERIE Pierre's avatar
ESTERIE Pierre committed
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
To find ScalFMM, `pkgconfig` can be used within your CMake and all ScalFMM dependencies will be found automatically.
Here is an example :

```cmake
find_package(scalfmm CONFIG REQUIRED)
if(scalfmm_FOUND)
  message(STATUS "ScalFMM Found")
  add_executable(my_exe program.cpp )
  target_link_libraries(my_exe scalfmm::scalfmm)
else()
  message(FATAL_ERROR "ScalFMM NOT FOUND")
endif()
```

## Documentation
The doc can be found [here](https://solverstack.gitlabpages.inria.fr/ScalFMM/) or you can build it locally.
104 105 106 107 108 109 110

```bash
cd scalfmm/Build
cmake .. -DSCALFMM_BUILD_DOC=ON # or if cmake has already been called, ccmake .
make doc
```

ESTERIE Pierre's avatar
ESTERIE Pierre committed
111
This will generate the documentation in HTML format in the `Build/Doc/html` folder.
112 113 114 115

```bash
# From the Build folder
cd Doc/html
ESTERIE Pierre's avatar
ESTERIE Pierre committed
116
firefox index.html
117
```
ESTERIE Pierre's avatar
ESTERIE Pierre committed
118 119 120
## Contributing and development guidelines

### Gitlab flow
121

ESTERIE Pierre's avatar
ESTERIE Pierre committed
122
Please, read the Gitlab flow article available [here](https://docs.gitlab.com/ee/workflow/gitlab_flow.html).
123

ESTERIE Pierre's avatar
ESTERIE Pierre committed
124 125 126
To make it simple, if you want to contribute to the library, create a branch from `master` with a meaningful name and develop
your feature in that branch. Keep your branch up to date by regularly rebasing your branch from the `master` branch to be up
to date. Once your are done, send a merge request.
127

ESTERIE Pierre's avatar
ESTERIE Pierre committed
128
## Help and News
129 130 131 132 133

You can subscribe to the scalfmm-public-users@lists.gforge.inria.fr mailing list (http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/scalfmm-public-users). The list is very low trafic (~ 2 mails per year), we will let you know of improvements and releases.

Contact the developers at : scalfmm-public-support@lists.gforge.inria.fr

ESTERIE Pierre's avatar
ESTERIE Pierre committed
134 135
## Folder structure
  - include : library core.
136 137 138 139 140 141
  - Data : particle distribution examples.
  - Examples : common usage examples.
  - Doc : documentation configuration.
  - UTests : unit tests.
  - Tests : examples to know how to use scalfmm/put particles in the tree/iterate on the tree...
  - Utils : some scripts and binaries to handle data files.