Commit d7a72e3f authored by COULAUD Olivier's avatar COULAUD Olivier

Documentation improvements.

	- The FAQ is available from dixygen web pages
       - add comments for epsilon parameter in Chebyschev kernels
      ...
To continue.
parent 3e5b1bed
// This page contains the special doxygen pages and mainpage.
/*!
/*! \page FAQ FAQ
*
* \section FAQ FAQ
* FAQ
*
* \subsection faq1 System/Compilers/Libraries Supported
* From our tests ScalFMM works with almost all configurations, except on Mac OS with the CLang compiler (or Intel compiler over CLang).
......@@ -20,6 +19,14 @@
*
* \subsection faq5 How to use MPI scalfmm?
* You must turn the cmake option on to activate the mpi tests.
*
* \subsection faq6 Accuracy of the Chebyshev FMM
* The ORDER template parameter sets the accuracy of the Chebyshev FMM while the EPSILON parameter introduces extra error but optimize the M2L step.
* In fact, in the Chebyshev FMM we perform compression on the M2L operators using various low rank approximation techniques
* (see https://arxiv.org/abs/1210.7292 for further details). Therefore we use a second accuracy criterion, namely EPSILON,
* in order to set the accuracy of these methods. For most kernels that we tested and in particular for 1/r, setting EPSILON=10^-ORDER d
* oes not introduce extra error in the FMM and captures the rank efficiently. If you think that for your kernel you need a better
* approximation of the M2L operators, then you can try to set EPSILON to 10 ^- (ORDER+{1,2,...}).
*/
......
......@@ -17,10 +17,11 @@
* \section contributors Contributors
*
* <ul>
* <li> Pierre Blanchard </li>
* <li> Berenger Bramas </li>
* <li> Olivier Coulaud </li>
* <li> Berenger Bramas </li>
* <li> Quentin Khan</li>
* <li> Cyrille Piacibello </li>
* <li> Pierre Blanchard </li>
* </ul>
* Previous contributors
......
......@@ -21,6 +21,9 @@
* <li> cd spack
* <li> bin/spack install scalfmm
* </ul>
* more documentation on spack and scalfmm is available at
* http://morse.gforge.inria.fr/spack/spack.html#sec-2-6
*
* You can stay in touch of the updates and new version by registering
* to the users mailing list
* (scalfmm-public-users@lists.gforge.inria.fr) which has a very low
......
/*! \page mainexamples Main Examples
/*! \page mainexamples Main Example
* \tableofcontents
* \section The repositories structure
* In the scalfmm directory, you can locate several folders. The
* sources folder called Src, the examples/tests folder Tests, the
* unit tests folders UTests, the Addons folder which contains one
* sub-folder per addon, the doc directory where you can find some
* documentation and the data folder which contains particles files or
* any other data needed per the simulation examples.
* In the scalfmm directory, you can locate several folders and the directory structure is as follows:
<ul>
<li> Src sources folder </li>
<ul>
<li>Arranger: ??</li>
<li>Components: Basic components.</li>
<li>Containers: The containers used in ScalFMM</li>
<li>Core: The different kind of parallel algorithms: Threads means OpenMP (fork-join, task, ...) while Proc is for MPI.</li>
<li>Extensions: ??</li>
<li>Files: our different loaders/wrtiters for particule (csvn vtk, FMA, ...)</li>
<li>GroupTree: A grouped octreed used with runtime system to improve the granularity.</li>
<li>Kernels: The different kernels available ins ScalFMM. One forlder per kernel. </li>
<li>Utils: All classes used inside the Library that are not specific to the FFM method.</li>
</ul>
<li> Examples Main drivers: distribution generation, FMM drivers (Rotation (1/r), Interpolation (Uniform and Chebyschev)</li>
<li> Tests. Other examples (prototpes) to understand how you can use the different features of ScalFMM.</li>
<li> UTests unit tests (CTEST)</li>
<li> Addons folder that contains one sub-folder per addon</li>
<li> Doc the documentation directory use Doxygen to generate it)</li>
<li> Data folder which contains particles files or any other data needed per the simulation examples.</li>
</ul>
*
* Here we focus mainly on the Tests and UTests folders, and we
* encourage users to look directly in the code file to see how things
* are made.
......
......@@ -51,7 +51,10 @@ method</b> based on interpolation ( Chebyshev or Lagrange).
*
* \subsection Publications
* <ul>
*<li> Bridging the gap between OpenMP 4.0 and native runtime systems for the fast multipole method, Emmanuel Agullo, Olivier Aumage, Berenger Bramas, Olivier Coulaud, Samuel Pitoiset. RR-8953, Inria. 2016, pp.49. <a href="https://hal.inria.fr/hal-01372022">hal-01372022</a></li>
*<li> Task-based FMM for heterogeneous architectures. Emmanuel Agullo, Berenger Bramas, Olivier Coulaud, Eric Darve, Matthias Messner, et al.. Concurrency and Computation: Practice and Experience, Wiley, 2016, 28 (9), <a href="http://onlinelibrary.wiley.com/doi/10.1002/cpe.3723/abstract;jsessionid=2AFE0326010BEA7DE21205D13EEB2EE1.f02t03">10.1002/cpe.3723</a></li>
* <li> Fast hierarchical algorithms for generating Gaussian random fields (<a href="https://hal.inria.fr/hal-01228519">https://hal.inria.fr/hal-01228519</a>)
*<li>Bérenger Bramas. Optimization and parallelization of the boundary element method for the wave equation in time domain. PhD of Université de Bordeaux, 2016. <a href="https://hal.inria.fr/tel-01306571/document">pdf</a> </li>
* <li>Task-based FMM for heterogeneous architectures, Emmanuel Agullo; Berenger Bramas; Olivier Coulaud,;Eric Darve; Matthias Messner; Toru Takahashi, Inria Research Report, 2014, pp. 29. <a href="http://hal.inria.fr/docs/00/97/46/74/PDF/RR-8513.pdf">RR-8513</a>
* <li> Task-Based FMM for Multicore Architectures, Emmanuel Agullo; Berenger Bramas; Olivier Coulaud , Eric Darve; Matthias Messner; Toru Takahashi SIAM Journal on Scientific Computing, SIAM, 2014, 36 (1), pp. 66-93
DOI : <a href="http://epubs.siam.org/doi/abs/10.1137/130915662"> 10.1137/130915662</a></li>
......@@ -61,6 +64,13 @@ method</b> based on interpolation ( Chebyshev or Lagrange).
*
* </ul>
*
*
* \subsection Projects Projects using ScalFMM
* If you want to add your project, please contact us. See \ref contacts page.
* <ul>
* <li> </li>
* </ul>
*/
......
......@@ -14,6 +14,7 @@ version 1.1
- ScalFMM on StarPu (runtime system) is available
- Add P2P ?? on GPU
- Add GPU version for ufmm (interpolation FMM based on uniform grid points)
- Fix bug in distribution generation
-
1.4
......
......@@ -32,17 +32,23 @@ class FTreeCoordinate;
/**
* @author Matthias Messner(matthias.messner@inria.fr)
* @class FChebKernel
* @brief
* Please read the license
* @brief Chebyshev interpolation based FMM operators for general non oscillatory kernels..
*
* This kernels implement the Chebyshev interpolation based FMM operators. It
* This class implements the Chebyshev interpolation based FMM operators. It
* implements all interfaces (P2P, P2M, M2M, M2L, L2L, L2P) which are required by
* the FFmmAlgorithm and FFmmAlgorithmThread.
* the FFmmAlgorithm, FFmmAlgorithmThread ...
*
* @tparam CellClass Type of cell
* @tparam ContainerClass Type of container to store particles
* @tparam MatrixKernelClass Type of matrix kernel function
* @tparam ORDER Chebyshev interpolation order
*
* The ORDER sets the accuracy of the Chebyshev FMM while the EPSILON parameter introduces extra error but optimize the M2L step.
* In fact, in the Chebyshev FMM we perform compression on the M2L operators using various low rank approximation techniques
* (see https://arxiv.org/abs/1210.7292 for further details). Therefore we use a second accuracy criterion, namely EPSILON,
* in order to set the accuracy of these methods. For most kernels that we tested and in particular for 1/r, setting EPSILON=10^-ORDER d
* oes not introduce extra error in the FMM and captures the rank efficiently. If you think that for your kernel you need a better
* approximation of the M2L operators, then you can try to set EPSILON to 10 ^- (ORDER+{1,2,...}).
*/
template < class FReal, class CellClass, class ContainerClass, class MatrixKernelClass, int ORDER, int NVALS = 1>
class FChebKernel
......@@ -66,6 +72,13 @@ public:
* The constructor initializes all constant attributes and it reads the
* precomputed and compressed M2L operators from a binary file (an
* runtime_error is thrown if the required file is not valid).
*
* @param[in] epsilon The compression parameter for M2L operator.
*
* The M2L optimized Chebyshev FMM implemented in ScalFMM are kernel dependent, but keeping EPSILON=10^-ORDER is usually fine.
* On the other hand you can short-circuit this feature by setting EPSILON to the machine accuracy,
* but this will significantly slow down the computations.
*
*/
FChebKernel(const int inTreeHeight, const FReal inBoxWidth, const FPoint<FReal>& inBoxCenter, const MatrixKernelClass *const inMatrixKernel,
const FReal Epsilon)
......@@ -79,6 +92,12 @@ public:
//M2LHandler->ReadFromBinaryFileAndSet();
M2LHandler->ComputeAndCompressAndSet();
}
/**
* The constructor initializes all constant attributes and it reads the
* precomputed and compressed M2L operators from a binary file (an
* runtime_error is thrown if the required file is not valid).
* Same as \see above constructor but the epsilon is automatically set to EPSILON=10^-ORDER
*/
FChebKernel(const int inTreeHeight, const FReal inBoxWidth, const FPoint<FReal>& inBoxCenter, const MatrixKernelClass *const inMatrixKernel)
: FChebKernel(inTreeHeight, inBoxWidth,inBoxCenter,inMatrixKernel,FMath::pow(10.0,static_cast<FReal>(-ORDER)))
......
......@@ -36,9 +36,9 @@ class FTreeCoordinate;
* @author Matthias Messner(matthias.messner@inria.fr)
* @class FChebSymKernel
* @brief
* Please read the license
* @brief Chebyshev interpolation based FMM operators for symmetric non oscillatory kernels..
*
* This kernels implement the Chebyshev interpolation based FMM operators
* This class implements the Chebyshev interpolation based FMM operators
* exploiting the symmetries in the far-field. It implements all interfaces
* (P2P, P2M, M2M, M2L, L2L, L2P) which are required by the FFmmAlgorithm and
* FFmmAlgorithmThread.
......@@ -47,6 +47,13 @@ class FTreeCoordinate;
* @tparam ContainerClass Type of container to store particles
* @tparam MatrixKernelClass Type of matrix kernel function
* @tparam ORDER Chebyshev interpolation order
*
* The ORDER sets the accuracy of the Chebyshev FMM while the EPSILON parameter introduces extra error but optimize the M2L step.
* In fact, in the Chebyshev FMM we perform compression on the M2L operators using various low rank approximation techniques
* (see https://arxiv.org/abs/1210.7292 for further details). Therefore we use a second accuracy criterion, namely EPSILON,
* in order to set the accuracy of these methods. For most kernels that we tested and in particular for 1/r, setting EPSILON=10^-ORDER d
* oes not introduce extra error in the FMM and captures the rank efficiently. If you think that for your kernel you need a better
* approximation of the M2L operators, then you can try to set EPSILON to 10 ^- (ORDER+{1,2,...}).
*/
template < class FReal, class CellClass, class ContainerClass, class MatrixKernelClass, int ORDER, int NVALS = 1>
class FChebSymKernel
......@@ -103,9 +110,15 @@ class FChebSymKernel
public:
/**
* The constructor initializes all constant attributes and it reads the
* \brief The constructor initializes all constant attributes and it reads the
* precomputed and compressed M2L operators from a binary file (an
* runtime_error is thrown if the required file is not valid).
*
* @param[in] epsilon The compression parameter for M2L operator.
*
* The M2L optimized Chebyshev FMM implemented in ScalFMM are kernel dependent, but keeping EPSILON=10^-ORDER is usually fine.
* On the other hand you can short-circuit this feature by setting EPSILON to the machine accuracy,
* but this will significantly slow down the computations.
*/
FChebSymKernel(const int inTreeHeight,
const FReal inBoxWidth,
......@@ -129,6 +142,9 @@ public:
* The constructor initializes all constant attributes and it reads the
* precomputed and compressed M2L operators from a binary file (an
* runtime_error is thrown if the required file is not valid).
*
* In the constructor the accuracy of The M2L optimized use the threshod rely -on the approximation order EPSILON=10^-ORDER.
*/
FChebSymKernel(const int inTreeHeight,
const FReal inBoxWidth,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment