From 9ecb10091aac41ee0efbae63eefa8650cdeb69b1 Mon Sep 17 00:00:00 2001 From: piacibel Date: Thu, 28 Nov 2013 14:23:37 +0100 Subject: [PATCH] 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 --- Src/Utils/Site_dox/FContact.dox | 24 +++ Src/Utils/Site_dox/FDownload.dox | 72 +++++++ Src/Utils/Site_dox/FLicense.dox | 20 ++ Src/Utils/Site_dox/FQuick.dox | 316 +++++++++++++++++++++++++++++++ Src/Utils/Site_dox/MainPage.dox | 53 ++++++ 5 files changed, 485 insertions(+) create mode 100644 Src/Utils/Site_dox/FContact.dox create mode 100644 Src/Utils/Site_dox/FDownload.dox create mode 100644 Src/Utils/Site_dox/FLicense.dox create mode 100644 Src/Utils/Site_dox/FQuick.dox create mode 100644 Src/Utils/Site_dox/MainPage.dox diff --git a/Src/Utils/Site_dox/FContact.dox b/Src/Utils/Site_dox/FContact.dox new file mode 100644 index 00000000..8d5d4fa6 --- /dev/null +++ b/Src/Utils/Site_dox/FContact.dox @@ -0,0 +1,24 @@ +/*! \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 + * + + * If you want to see others projects of HiePACS Inria teams, please + * see : https://team.inria.fr/hiepacs/ . + + * \section contributors Contributors + * + + + */ + diff --git a/Src/Utils/Site_dox/FDownload.dox b/Src/Utils/Site_dox/FDownload.dox new file mode 100644 index 00000000..372e14ba --- /dev/null +++ b/Src/Utils/Site_dox/FDownload.dox @@ -0,0 +1,72 @@ +/*! \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 +* +* +* +* \section build Build +* How to build ScalFMM +* +* +* \subsection conf Configuration of the build +* +* This is all the build options you can modify. +* +* +* +* You may want to install it : $> make install . 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 $> make doc in the Build directory. + +* +* +*/ diff --git a/Src/Utils/Site_dox/FLicense.dox b/Src/Utils/Site_dox/FLicense.dox new file mode 100644 index 00000000..bfb8a53e --- /dev/null +++ b/Src/Utils/Site_dox/FLicense.dox @@ -0,0 +1,20 @@ +/*! \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. + * + * + */ diff --git a/Src/Utils/Site_dox/FQuick.dox b/Src/Utils/Site_dox/FQuick.dox new file mode 100644 index 00000000..489292f1 --- /dev/null +++ b/Src/Utils/Site_dox/FQuick.dox @@ -0,0 +1,316 @@ +/*! \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: + + + * 
+ * class FAbstractParticleContainer{
+ 
+ * template
+ * void push(const FPoint& , Args ... ){
+    
+ * };
+ *
+ + * 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: + + * 
 
+  * 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; 
+  *  }; 
+
+ *
+ + * 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 : + + * 
+ * 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; 
+ *   }; 
+ *
+ + * 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: + + * 
+ * typedef FVector                                        ContainerClass;
+ * typedef FSimpleLeaf                        LeafClass;
+ * typedef FOctree  OctreeClass;
+ * OctreeClass tree(HEIGHT, SUBHEIGHT, BoxWidth, CenterOfBox);
+ *
+ + * \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 : + + * 
+ * template  
+ *   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  
+ *   void fillTree(OctreeClass& tree){ 
+ *       ParticleClass particleToFill; 
+ *       for(int idxPart = 0 ; idxPart < getNumberOfParticles() ; ++idxPart){ 
+ *           fillParticle(particleToFill); 
+ *           tree.insert(particleToFill); 
+ *       } 
+ *   } 
+ *  }; 
+ *
+ + * 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 : + + * 
+ * FRandomLoader loader(NbPart, 1, FPoint(0.5,0.5,0.5), 1);
+ * OctreeClass tree(10, 3, loader.getBoxWidth(), loader.getCenterOfBox());
+ * loader.fillTree(tree);
+ *
+ + * \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 : + + * 
+ * OctreeClass::Iterator octreeIterator(&tree);
+ *     octreeIterator.gotoBottomLeft();
+ *     int counter = 0;
+ *     do{
+ *             ++counter;
+ *     } while(octreeIterator.moveRight());
+ *
+ + * To iterate on the cells we can proceed as follow : + * 
+ * 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";
+ * }
+ *
+ + * \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 : + + * 
+ * template< class ParticleClass, class CellClass, class ContainerClass> class FBasicKernels : public FAbstractKernels { 
+ * 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 ){}
+ *
+ + * 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. + + * 
+ * typedef FTestKernels         KernelClass;
+ * KernelClass kernels;
+ *
+ + * \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 : + + * 
+ * typedef FFmmAlgorithm     FmmClass;
+ * FmmClass algo(&tree,&kernels);
+ * algo.execute();
+ *
+ + * To move to the OpenMP threaded FMM we can use the fallowing code by + * changing 'FFmmAlgorithm' per 'FFmmAlgorithmThread' : + + * 
+ * typedef FFmmAlgorithmThread     FmmClass;
+ * FmmClass algo(&tree,&kernels);
+ * algo.execute();
+ *
+ + \section reasons The reasons why ... + + * Of course the library is changing and re-factorized usually but + * lets discuss about 'The reasons why' : + + * + +*/ diff --git a/Src/Utils/Site_dox/MainPage.dox b/Src/Utils/Site_dox/MainPage.dox new file mode 100644 index 00000000..87bcbbb8 --- /dev/null +++ b/Src/Utils/Site_dox/MainPage.dox @@ -0,0 +1,53 @@ +// 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: + * + * + * + * 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. + * + */ + + + -- GitLab