Commit 9ecb1009 authored by PIACIBELLO Cyrille's avatar PIACIBELLO Cyrille

In Src/Utils/Site_dox/ you can find different files containing all the...

In Src/Utils/Site_dox/ you can find different files containing all the information that was given by Site and Wiki. Simply make doc, and open Build/Doc/html/index.html with a browser to see it. I will update the online doc after your advices. The Contributor section of FContact.dox is empty, because I didn't have the names neither the adresse of the contributors
parent 9df34042
/*! \page contacts Contacts
*
* \section authors Authors
* ScalFmm is a library for the Fast Multipole Method (FMM). It is
* written in C++ and use OpenMP and MPI to support parallel
* execution. It is developed by the HiePACS team at the INRIA.
* You can contact the development team for any questions at
* <ul>
* <li> berenger.bramas@inria.fr </li>
* <li> olivier.coulaud@inria.fr </li>
* <li> cyrille.piacibello@inria.fr</li>
* </ul>
* If you want to see others projects of HiePACS Inria teams, please
* see : https://team.inria.fr/hiepacs/ .
* \section contributors Contributors
*
*/
/*! \page install Downloading, Building and Installing ScalFMM
*
* \section download Download ScalFMM
*
* To download ScalFmm go on http://scalfmm-public.gforge.inria.fr/download.html.
*
* 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
* traffic (one email per month) at :
* http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/scalfmm-public-users.
*
* \section secNecessary Require
*
* <ul>
* <li> CMake for compiling, ccmake for configuring the build </li>
* <li> Open MP </li>
* <li> MPI, if you want to use distributed version of the algorithm </li>
* <li> A compiler supporting C++ 2011 </li>
* </ul>
*
* \section build Build
* How to build ScalFMM
* <ul>
* <li> Go to scalfmm/Build directory </li>
* <li> type <b> $> cmake .. </b>
* <ul>
* <li> If you want to enable MPI, use <b> $> cmake .. -DSCALFMM_USE_MPI=ON </b> </li>
* </ul>
* </li>
* <li> then configure your build with <b> $> ccmake .. </b> if needed </li>
* <li> then type <b> $> make name_of_exec </b> </li>
* </ul>
*
* \subsection conf Configuration of the build
*
* This is all the build options you can modify.
*
* <ul>
* <li> CMAKE_INSTALL_PREFIX : to choose where to install ScalFmm </li>
* <li> DSCALFMM_USE_MPI : to use and enable MPI. Warning, you need to use this parameter at the first cmake command you write. </li>
* <li> SCALFMM_ATTACHE_SOURCE : to build with -g </li>
* <li> SCALFMM_BUILD_DEBUG : to build in debug mode of cmake (with -O0) </li>
* <li> SCALFMM_BUILD_TESTS : to build the text and the examples </li>
* <li> SCALFMM_BUILD_UTESTS : to build the unit tests </li>
* <li> SCALFMM_USE_ADDONS : to activate add ons </li>
* <ul>
* <li> SCALFMM_ADDON_FMMAPI : to build Fmm Api </li>
* </ul>
* <li> SCALFMM_USE_DOUBLE_PRECISION : to build in double precision </li>
* <li> SCALFMM_USE_MEM_STATS : to use memory stats (which count any new/delete done during a simulation) </li>
* <li> SCALFMM_USE_BLAS : to enable blas (needed by most of the kernel) </li>
* <ul>
* <li> SCALFMM_USE_MKL_AS_BLAS : to use MKL as blas </li>
* </ul>
* <li> SCALFMM_USE_TRACE : to create trace </li>
* <ul>
* <li> SCALFMM_USE_ITAC : to use Intel ITAC tool as trace generator </li>
* </ul>
* </ul>
*
* You may want to install it : <b> $> make install </b>. Note that it
* is not an obligation to install ScalFmm to use it. You can build it
* and use it from the Build directory.
*
* The whole project is documented using Doxygen. You can build the doc
* by typing <b> $> make doc </b> in the Build directory.
*
*
*/
/*! \page License License information
*
*
* The library is under LGPL + CeCILL-C licenses. In case of conflict
* the more restrictive has to be used. We encourage users to have a
* look to the official license websites in case of doubts.
*
* See the GNU General Public and CeCILL-C Licenses for more details.
* "http://www.cecill.info". "http://www.gnu.org/licenses".
*
* ScalFmm is under software patent number
* IDDN.FR.001.100030.000.S.P.2012.000.31235. If you need a more
* flexible license, please do not hesitate to contact us.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
*
*
*/
/*! \page quick Quick Start
* In this section, we present the data structure organization and the
* classes design to understand fully ScalFmm.
* \tableofcontents
* \section prerequisite Prerequisite
* In it is better to have built the library or at minimum to have
* downloaded the sources. The user needs to be comfortable with 'C++'
* language and if possible templates.
* \section data What Data
* In ScalFmm we proceed the Fast Multipole Method. New users should see
* this process has a way to estimate far interactions and compute
* accurately the close interactions in a group of particles. We then
* have some particles that we insert in a octree. The octree stores the
* particles in its leaves. From the root to the leaves there are the
* cells. At this point we only express primitives classes which hold
* data or primitives classes.
* Then, we need a kernel which is computational part of the FMM. It is a
* class that is able to compute the interactions between particles or
* cells, etc. There is several possible kernels depending on what we
* want to compute.
* Finally, the FMM Core algorithm is a class that takes the primitives
* classes and calls the kernel with the correct arguments. In our
* implementation, the user has to choose between sequential FMM or
* OpenMP FMM.
* \section primitivesclasses Primitives Classes
* \subsection particles Particles
* To be stored in the octree, a particle must inherites
* FAbstractParticleContainer. This is the class needed:
* <pre class='brush: cpp'>
* class FAbstractParticleContainer{
* template<typename... Args>
* void push(const FPoint& , Args ... ){
* };
* </pre>
* A class implements this minimum required methods, it is
* FBasicParticleContainer. This is what MUST proposes a particle
* class to be able to be inserted in the tree. Then, the user can add
* other methods to match the kernel requirement. For example, some
* kernel may need a particle to hold a physical value, a forces
* vector and a potential. See FRotationParticleContainer if you want
* an example of a Particle class.
* \subsection cells Cells
* The same principle apply to cells. There is a minimum sets of
* methods that must propose a cell class to be able to be used in the
* octree. And then, there are some other methods that you can add to
* make it usable per the kernel.
* The class Src/Components/FAbstractCell.hpp shows what should
* implement a cell:
* <pre class='brush: cpp'>
* class FAbstractCell{
* public:
* virtual ~FAbstractCell(){
* }
* virtual MortonIndex getMortonIndex() const = 0;
* virtual void setMortonIndex(const MortonIndex inIndex) = 0;
* virtual void setPosition(const FPoint& inPosition) = 0;
* virtual const FTreeCoordinate& getCoordinate() const = 0;
* virtual void setCoordinate(const long inX, const long inY, const long inZ) = 0;
* virtual bool hasSrcChild() const = 0;
* virtual bool hasTargetsChild() const = 0;
* virtual void setSrcChildTrue() = 0;
* virtual void setTargetsChildTrue() = 0;
* };
* </pre>
* The FBasicCell class provides an implementation of all these
* methods.
* \subsection leaves Leaves
* The leaf is the class responsible of hosting the particles. The
* octree uses this class and order to store a particle. Behind the
* scene, the leaf does what it wants. But, the octree also needs a way
* to get the particles it has inserted which can be targets or
* sources
* In the following class, FAbstractLeaf, one can see what is required
* by the algorithm :
* <pre>
* template< class ParticleClass, class ContainerClass >
* class FAbstractLeaf {
* public:
* // Default destructor
* virtual ~FAbstractLeaf(){
* }
* virtual void push(const ParticleClass& particle) = 0;
* virtual ContainerClass* getSrc() = 0;
* virtual ContainerClass* getTargets() = 0;
* };
* </pre>
* The FSimpleLeaf class provides an implementation of all thes
* methods.
* \section octree Octree
* The octree is templatized and then can host particles, cells and
* leaves. It also needs some information about the simulation like the
* size and the center of the box. Moreover, the user has to precise
* the height of the octree. The root is the level 0, so giving a
* height of 3 creates the root level, a cells level and the leaves
* level. The usual way of declaring the octree, taken from
* Tests/Utils/testOctree.cpp, is as follow:
* <pre>
* typedef FVector<FBasicParticle> ContainerClass;
* typedef FSimpleLeaf<FBasicParticle, ContainerClass > LeafClass;
* typedef FOctree<FBasicParticle, FBasicCell, ContainerClass , LeafClass > OctreeClass;
* OctreeClass tree(HEIGHT, SUBHEIGHT, BoxWidth, CenterOfBox);
* </pre>
* \subsection loading Loading Particle
* Once the octree is created, we need to put some particles in
* it. This is perform using classes called 'loader'.
* A loader should proposes theses methods :
* <pre>
* template <class ParticleClass>
* class FAbstractLoader {
* public:
* // Default destructor
* virtual ~FAbstractLoader(){
* }
* virtual FSize getNumberOfParticles() const = 0;
* virtual FPoint getCenterOfBox() const = 0;
* virtual FReal getBoxWidth() const = 0;
* virtual bool isOpen() const = 0;
* virtual void fillParticle(ParticleClass& inParticle) = 0;
* template <class OctreeClass>
* void fillTree(OctreeClass& tree){
* ParticleClass particleToFill;
* for(int idxPart = 0 ; idxPart < getNumberOfParticles() ; ++idxPart){
* fillParticle(particleToFill);
* tree.insert(particleToFill);
* }
* }
* };
* </pre>
* There exist several loaders; one per file format. Depending of the
* loader, the particle class should implement special methods. For
* example, the basic loader only fill the position of the
* particles. Whereas, the FMA loader also fill the physical value of
* the particles.
* The usual way of loading the particle is as follow :
* <pre>
* FRandomLoader<ParticleClass> loader(NbPart, 1, FPoint(0.5,0.5,0.5), 1);
* OctreeClass tree(10, 3, loader.getBoxWidth(), loader.getCenterOfBox());
* loader.fillTree(tree);
* </pre>
* \subsection octreeIterator Iterating on an Octree
*If the user wants to iterate on the tree and access the particles or
*the cells. To do so, he needs to declare an iterator and use it to
*move from top to bottom and from left to right. It is critical that
*the octree is not empty!
* This next sample is taken from Tests/Utils/testOctreeIter.cpp and
* count the leaves :
* <pre>
* OctreeClass::Iterator octreeIterator(&tree);
* octreeIterator.gotoBottomLeft();
* int counter = 0;
* do{
* ++counter;
* } while(octreeIterator.moveRight());
* </pre>
* To iterate on the cells we can proceed as follow :
* <pre>
* OctreeClass::Iterator octreeIterator(&tree);
* octreeIterator.gotoBottomLeft();
* for(int idxLevel = NbLevels - 1 ; idxLevel >= 1 ; --idxLevel ){
* int counter = 0;
* do{
* ++counter;
* } while(octreeIterator.moveRight());
* octreeIterator.moveUp();
* octreeIterator.gotoLeft();
* std::cout << "Cells at level " << idxLevel << " = " << counter << " ...\n";
* }
* </pre>
* \section kernel The kernel
* The kernel is a class that should perform the usual FMM
* operators. Each kind of kernel may require special methods and
* needs on the particles and the cells.
* An empty kernel can be found in Src/Components/FBasicKernels.hpp,
* it implements the class definition FAbstractKernels :
* <pre>
* template< class ParticleClass, class CellClass, class ContainerClass> class FBasicKernels : public FAbstractKernels<ParticleClass,CellClass,ContainerClass> {
* public:
*
* // Default destructor
* virtual ~FBasicKernels(){}
* virtual void P2M(CellClass* const , const ContainerClass* const ) {}
* virtual void M2M(CellClass* const FRestrict , const CellClass*const FRestrict *const FRestrict , const int ) {}
* virtual void M2L(CellClass* const FRestrict , const CellClass* [], const int , const int ) {}
* virtual void L2L(const CellClass* const FRestrict , CellClass* FRestrict *const FRestrict , const int ) {}
* virtual void L2P(const CellClass* const , ContainerClass* const ){}
* virtual void P2P(const FTreeCoordinate& ,
* ContainerClass* const FRestrict , const ContainerClass* const FRestrict ,
* ContainerClass* const [27], const int ){}
* virtual void P2PRemote(const FTreeCoordinate& ,
* ContainerClass* const FRestrict , const ContainerClass* const FRestrict ,
* ContainerClass* const [27], const int ){}
* </pre>
* One example of kernel is the 'test' kernel called
* FTestKernels. This kernels simply sum the particles (one particle
* weigh = 1) so at the end of the simulation each particles should be
* have a weigh of N. We just declare this kernel based on the
* components type but usually do not call any method manually since
* this is performed per the FMM core.
* <pre>
* typedef FTestKernels<ParticleClass, CellClass, ContainerClass > KernelClass;
* KernelClass kernels;
* </pre>
* \section coreFMM The FMM Core
* We showed how to have an octree and a kernel. Now, we show how to use
* a Fmm Algorithm on the data. Remember, the FMM algorithm simply
* takes the data from the octree and call the method of the
* kernel. The goal is to have a FMM independent from the data.
* The next sample is taken from Tests/Utils/testFmmAlgorithm.cpp and
* use the basic sequential FMM :
* <pre>
* typedef FFmmAlgorithm<OctreeClass, ParticleClass, CellClass, ContainerClass, KernelClass, LeafClass > FmmClass;
* FmmClass algo(&tree,&kernels);
* algo.execute();
* </pre>
* To move to the OpenMP threaded FMM we can use the fallowing code by
* changing 'FFmmAlgorithm' per 'FFmmAlgorithmThread' :
* <pre>
* typedef FFmmAlgorithmThread<OctreeClass, ParticleClass, CellClass, ContainerClass, KernelClass, LeafClass > FmmClass;
* FmmClass algo(&tree,&kernels);
* algo.execute();
* </pre>
\section reasons The reasons why ...
* Of course the library is changing and re-factorized usually but
* lets discuss about 'The reasons why' :
* <ul>
* <li> Every things is templatized :
* <blockquote>
* The reason is to avoid the use of virtual and abstract class. In
* this page we present some abstract classes, but they are not really
* use. They only define the need, the minimum required to implement a
* particle or a cell. But the kernels should not work on an abstract
* type but on the real data. This enable lots of compiler
* optimizations and avoid the use of V-Table.
* </blockquote>
* </li>
* <li>
* Some destructors are not virtual :
* <blockquote>
* As we said, the objective of the class are not to be inherited. So
* a virtual destructor is not needed.
* </blockquote>
* </li>
* <li>
* Typedef is used like this :
* <blockquote>
* It can take some time to understand how it works. But all our users
* finally like the way of using typedef and template. As you will see
* in most of the example the struct is the same and you will not be
* lost since in any example 'ParticleClass' is used for the particle
* type and so on.
* </blockquote>
* </li>
* </ul>
*/
// This page contains the special doxygen pages and mainpage.
/*!
* @mainpage ScalFmm
*
* \section overV Overview
*
* ScalFMM is a software library to simulate N-body interactions using
* the Fast Multipole Method.
*
* The library offers two methods to compute interactions between
* bodies when the potential decays like 1/r. The first method is the
* classical FMM based on spherical harmonic expansions and the second is
* the Black-Box method which is an independent kernel formulation
* (introduced by E. Darve @ Stanford). With this method, we can now
* easily add new non oscillatory kernels in our library. For the
* classical method, two approaches are used to decrease the complexity
* of the operators. We consider either matrix formulation that allows us
* to use BLAS routines or rotation matrices to speed up the M2L
* operator.
*
* ScalFMM intends to offer all the functionalities needed to perform
* large parallel simulations while enabling an easy customization of
* the simulation components: kernels, particles and cells. It works
* in parallel in a shared/distributed memory model using OpenMP and
* MPI. The software architecture has been designed with two major
* objectives: being easy to maintain and easy to understand. There is
* two main parts:
* <ul>
* <li> the management of the octree and the
* parallelization of the method; </li>
* <li> The kernels. This new
* architecture allow us to easily add new FMM algorithm or kernels
* and new paradigm of parallelization. </li>
* </ul>
*
*
* To download build and install the application, please see \ref
* install.
*
* The \ref quick can help you to understand the architectur of the
* library.
*
* This software is distributed under a specific License. For more
* informations, see \ref License.
*
* If you want to cite the project and/or the team, please contact
* us. See \ref contacts page.
*
*/
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