FQuick.dox 15.4 KB
Newer Older
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
1 2 3
/*! \page quick Quick Start

 * In this section, we present the data structure organization and the 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
4 5 6 7 8
 * classes design to understand fully ScalFmm and customized it.
 
 * Remark : There is a big difference between the version 1.0 and 2.0
 * since we do not store array of particles anymore but rather several arrays.
 * This was needed in order to be able to vectorize the P2P code. 
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
9 10 11 12 13
 
 * \tableofcontents 
 
 * \section prerequisite Prerequisite 
 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
14 15
 * It is recommanded to have built the library or at minimum to have 
 * downloaded the sources code. The user needs to be comfortable with 'C++' 
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
16 17
 * language and if possible templates. 

18 19
 * If you want to browse the code, you may want to see first our \ref
   rules.
20

PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
21 22 23 24 25 26 27 28
 * \section classes Overview of general architecture
 *
 * \image html Classes.png "General architecture"
 
 * \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 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
29 30
 * accurately the close interactions in a group of particles. We start 
 * with some particles that we insert in a octree. The octree stores the 
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
31 32 33 34 35 36 37
 * 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 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
38
 * want to compute and it is easy to implement your own.
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
39 40 41 42
 
 * 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 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
43
 * OpenMP FMM or even MPI FMM. 
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
44 45 46 47 48
 
 * \section primitivesclasses Primitives Classes
 
 * \subsection particles Particles
 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
49 50 51 52 53 54
 * In order to put the particles in the right leaf, the octree needs to know its spatial position.
 * Then, then once the right leaf is found it is allocated (using the given template LeafClass of the octree),
 * and the particles is pushed into the leaf. If a basic leaf is used, this one only push to a particles container
 * what it has received. So a particles container is nothing more than a class that has a push method
 * which matches the one you call on the octree. To ensure that,
 * a particle container should inherit from FAbstractParticleContainer.
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
55 56

 * <pre class='brush: cpp'>
BRAMAS Berenger's avatar
BRAMAS Berenger committed
57
 * class FAbstractParticleContainer{ 
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
58 59
 * template<typename... Args>
 * void push(const FPoint& , Args ... ){
BRAMAS Berenger's avatar
BRAMAS Berenger committed
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
 *      // This method should be specialed
 * };
 * </pre>
 
 * Here is how we can print the index of the particles that is inserted from a particles containers :
 
 
 * <pre class='brush: cpp'>
 * class MyCustomContainer : public FAbstractParticleContainer{ 
 * template<typename... Args>
 * void push(const FPoint& , int particleIndex, double anythingElse){
 *      std::cout << "The particle " << particleIndex << " has just been inserted with " << anythingElse << "\n";
 * };
 *
 * // In the main
 *     typedef MyCustomContainer      ContainerClass;
 *     typedef FSimpleLeaf< ContainerClass >                     LeafClass;
 *     typedef FOctree< FBasicCell, ContainerClass , LeafClass >  OctreeClass;
 * // From your system properties
 * OctreeClass tree(treeHeight, subHeight, loader.getBoxWidth(), loader.getCenterOfBox());
 *
 * // Add a particle
 * tree.push(FPoint(x, y, z), particleIndex, anythingElse);
 * // The octree will push in the FSimpleLeaf which will push in the MyCustomContainer which will print the message.
 * </pre>
 
 * In the same way you can sort your particles in different buffer by passing a flag which will be passed to your container:
 
  * <pre class='brush: cpp'>
 * class MyCustomContainer : public FAbstractParticleContainer{ 
 * std::vector<int> bigParticles;
 * std::vector<int> smallParticles;
 * template<typename... Args>
 * void push(const FPoint& , bool isBig, int particleIndex){
 *      if(isBig) bigParticles.push_back(particleIndex);
 *      else smallParticles.push_back(particleIndex);        
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
96
 * };
BRAMAS Berenger's avatar
BRAMAS Berenger committed
97 98 99 100 101 102 103 104 105 106 107
 *
 * // In the main
 *     typedef MyCustomContainer      ContainerClass;
 *     typedef FSimpleLeaf< ContainerClass >                     LeafClass;
 *     typedef FOctree< FBasicCell, ContainerClass , LeafClass >  OctreeClass;
 * // From your system properties
 * OctreeClass tree(treeHeight, subHeight, loader.getBoxWidth(), loader.getCenterOfBox());
 *
 * // Add a particle
 * tree.push(FPoint(x, y, z), boolIsBigParticle, particleIndex);
 * // The octree will push in the FSimpleLeaf which will push in the MyCustomContainer which will store idx in the correct vector
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
108 109
 * </pre>

BRAMAS Berenger's avatar
BRAMAS Berenger committed
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
 * The FBasicParticleContainer class is given for those who would like to store one or several data type
 * of the same kind per particles (and their position).
 * For example if some one want to store one (or several) integers for the particles or
 * one (or several) double values per particles.
 
 
  * <pre class='brush: cpp'>
 *  // Declaration
 * template <unsigned NbAttributesPerParticle, class AttributeClass = FReal >
 * class FBasicParticleContainer : public FAbstractParticleContainer, public FAbstractSerializable;
  * </pre>
  
 * If for example you would like to store 2 doubles per particles (one intialized during the push
 * wherease the other if set to 0) you can use the following code: 
 
  * <pre class='brush: cpp'>
 *     typedef FBasicParticleContainer< 2, double>      ContainerClass;
 *     typedef FSimpleLeaf< ContainerClass >                     LeafClass;
 *     typedef FOctree< FBasicCell, ContainerClass , LeafClass >  OctreeClass;
 * // From your system properties
 * OctreeClass tree(treeHeight, subHeight, loader.getBoxWidth(), loader.getCenterOfBox());
 *
 * // Add a particle
 * tree.push(FPoint(x, y, z), myFirstDouble); //, mySecondValueIfNotZero);
 *
 * // Then to print all the doubles value :
 * tree.forEachLeaf([&](LeafClass* lf){
 *      ContainerClass* container = lf->getSrc();
 *      int nbParticlesInLeaf = container->getNbParticles();
 *      double* x_pos = container->getPositions()[0];
 *      double* y_pos = container->getPositions()[1];
 *      double* z_pos = container->getPositions()[2];
 *      double* firstDoubleArray = container->getAttribute(0); // same as getAttribute<0>()
 *      double* secondDoubleArray = container->getAttribute(1); // same as getAttribute<1>()
 *
 *      for(int idxPart = 0 ; idxPart < nbParticlesInLeaf ; ++idxPart){
 *          std::cout << "Particle inserted " << idxPart << " in the leaf\n";
 *          std::cout << "Has position " << x_pos[idxPart] << " " << y_pos[idxPart] << " " << z_part[idxPart] << "\n";
 *          std::cout << "And values " << firstDoubleArray[idxPart] << " and " << secondDoubleArray[idxPart] << "\n";
 *      }
 * });
 * </pre>
 
 
 * Therefor, we propose a particle container called FP2PParticleContainer to store the position,
 * a force vector, a potential and a physical value per particle.
 * This container is one used in our kernels and you can read our P2P (or P2M/L2P) in order to catch
 * the way it works.
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
158 159 160 161 162 163

 * \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
BRAMAS Berenger's avatar
BRAMAS Berenger committed
164
 * make it usable per your kernel.
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
165 166 167 168 169 170 171 172 173 174 175 176 177 178

 * 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; 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
179 180 181 182
  *  virtual bool hasSrcChild() const = 0;  // Needed if TSM (target source model) is used
  *  virtual bool hasTargetsChild() const = 0;   // Needed if TSM (target source model) is used
  *  virtual void setSrcChildTrue() = 0;   // Needed if TSM (target source model) is used
  *  virtual void setTargetsChildTrue() = 0;   // Needed if TSM (target source model) is used
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
  *  }; 
 * </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 :

BRAMAS Berenger's avatar
BRAMAS Berenger committed
200
 * <pre class='brush: cpp'> 
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
201 202 203 204 205
 * template< class ParticleClass, class ContainerClass > 
 *   class FAbstractLeaf { 
 *   public: 
 *   // Default destructor
 *   virtual ~FAbstractLeaf(){ 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
206 207 208 209 210
 *   }     
 *  template<typename... Args>
 *   void push(const FPoint& inParticlePosition, Args ... args){
 *       FLOG( FLog::Controller.write("Warning, push is not implemented!").write(FLog::Flush) );
 *   }
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
211 212 213 214 215
 *   virtual ContainerClass* getSrc() = 0; 
 *   virtual ContainerClass* getTargets() = 0; 
 *   }; 
 * </pre>

BRAMAS Berenger's avatar
BRAMAS Berenger committed
216
 * The FSimpleLeaf class provides an implementation of all these methods.
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
217 218 219
 
 * \subsection loading Loading Particle

BRAMAS Berenger's avatar
BRAMAS Berenger committed
220 221 222
 * In most of our examples, we are using "loaders" which are classes used to manage the files.
 * They returned the physical properties (box width, center of box, ...) which are used to build the octree.
 * Then they are used to get the particle positions (and their physical values if appropriate).
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
223

BRAMAS Berenger's avatar
BRAMAS Berenger committed
224
 * <pre class='brush: cpp'> 
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
225 226 227 228 229 230 231 232 233 234
 * 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; 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
235
 *   void fillTree(FPoint& particlesPos);
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
236 237 238
 *  }; 
 * </pre>

BRAMAS Berenger's avatar
BRAMAS Berenger committed
239 240 241 242
 * There exist several loaders; one per file format.
 * Usually we do as the following:
 * <pre class='brush: cpp'> 
 * FRandomLoader loader(NbPart, 1, FPoint(0.5,0.5,0.5), 1);
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
243
 * OctreeClass tree(10, 3, loader.getBoxWidth(), loader.getCenterOfBox());
BRAMAS Berenger's avatar
BRAMAS Berenger committed
244 245 246 247 248
 * FPoint particlePosition;
 * for(int idxPart = 0 ; idxPart < loader.getNumberOfParticles() ; ++idxPart){
 *     loader.fillParticle(&particlePosition);
 *     tree.insert(particlePosition);
 * }
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
249 250 251 252
 * </pre>

 * \subsection octreeIterator Iterating on an Octree
 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
253 254
 * There are two ways to iterate on the data of an octree :
 * Using an iterator, or using a lambda function.
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
255

BRAMAS Berenger's avatar
BRAMAS Berenger committed
256
 * This next sample is taken from Tests/Utils/testOctreeIter.cpp and count the leaves :
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
257
 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
258
 * <pre class='brush: cpp'> 
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
259 260 261 262 263 264 265
 * OctreeClass::Iterator octreeIterator(&tree);
 *     octreeIterator.gotoBottomLeft();
 *     int counter = 0;
 *     do{
 *             ++counter;
 *     } while(octreeIterator.moveRight());
 * </pre>
BRAMAS Berenger's avatar
BRAMAS Berenger committed
266 267 268 269 270
 * But here is the equivalent using lambda function:
 * long counter = 0;
 * tree.forEachLeaf([&](LeafClass* leaf){
 *      ++counter;
 * });
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
271 272

 * To iterate on the cells we can proceed as follow :
BRAMAS Berenger's avatar
BRAMAS Berenger committed
273
 * <pre class='brush: cpp'> 
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
274 275 276 277 278 279 280 281 282 283 284 285
 * 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>
BRAMAS Berenger's avatar
BRAMAS Berenger committed
286 287 288 289 290 291
 * Here is an equivalent:
  * <pre class='brush: cpp'> 
  *  long nbCells[TreeHeight];
  *  tree.forEachCellWithLevel([&nbCells](CellClass* cell, int idxLevel){
  *      nbCells[idxLevel] += 1;
  *  });
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
292 293 294

 * \section kernel The kernel
 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
295
 * Kernel refers to the class that perform the computation.
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
296 297 298 299

 * An empty kernel can be found in Src/Components/FBasicKernels.hpp,
 * it implements the class definition FAbstractKernels :

BRAMAS Berenger's avatar
BRAMAS Berenger committed
300 301
 * <pre class='brush: cpp'> 
 * template< class CellClass, class ContainerClass> class FBasicKernels : public FAbstractKernels<CellClass,ContainerClass> { 
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325
 * 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.

BRAMAS Berenger's avatar
BRAMAS Berenger committed
326 327
 * <pre class='brush: cpp'> 
 * typedef FTestKernels<CellClass, ContainerClass >         KernelClass;
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
328 329 330 331 332 333 334 335 336 337 338 339 340
 * 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 :
 
BRAMAS Berenger's avatar
BRAMAS Berenger committed
341 342
 * <pre class='brush: cpp'> 
 * typedef FFmmAlgorithm<OctreeClass, CellClass, ContainerClass, KernelClass, LeafClass >     FmmClass;
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
343 344 345 346 347 348 349
 * 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' :

BRAMAS Berenger's avatar
BRAMAS Berenger committed
350 351
 * <pre class='brush: cpp'> 
 * typedef FFmmAlgorithmThread<OctreeClass, CellClass, ContainerClass, KernelClass, LeafClass >     FmmClass;
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
352 353 354 355 356 357 358 359 360 361 362 363 364 365
 * 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
BRAMAS Berenger's avatar
BRAMAS Berenger committed
366 367
 * use. They only define what we need, the minimum required to implement a
 * particle container or a cell. But the kernels should not work on an abstract
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
368 369 370 371 372 373 374 375 376 377
 * type but on the real data. This enable lots of compiler
 * optimizations and avoid the use of V-Table.
 * </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
BRAMAS Berenger's avatar
BRAMAS Berenger committed
378 379
 * in most of the examples the struct is the same and you will not be
 * lost.
PIACIBELLO Cyrille's avatar
PIACIBELLO Cyrille committed
380 381 382 383 384 385 386
 * </blockquote>
 * </li>

 
 * </ul>

*/