Merge branch 'master' of git+ssh://scm.gforge.inria.fr//gitroot//scalfmm/scalfmm

Src/Utils/Site_dox/FContact.dox

+/*! \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
+ *
+ 
+
+ */
+ 

Src/Utils/Site_dox/FDownload.dox

+/*! \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.
+
+*
+*
+*/

Src/Utils/Site_dox/FLicense.dox

+/*! \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.  
+ *
+ *
+ */

Src/Utils/Site_dox/FQuick.dox

+/*! \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>
+
+*/

Src/Utils/Site_dox/MainPage.dox

+// 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.
+ *
+ */
+
+
+