From 9ecb10091aac41ee0efbae63eefa8650cdeb69b1 Mon Sep 17 00:00:00 2001 From: piacibel <cyrille.piacibello@inria.fr> 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 000000000..8d5d4fa6c --- /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 + * <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 + * + + + */ + diff --git a/Src/Utils/Site_dox/FDownload.dox b/Src/Utils/Site_dox/FDownload.dox new file mode 100644 index 000000000..372e14bab --- /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 +* +* <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. + +* +* +*/ diff --git a/Src/Utils/Site_dox/FLicense.dox b/Src/Utils/Site_dox/FLicense.dox new file mode 100644 index 000000000..bfb8a53e7 --- /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 000000000..489292f11 --- /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: + + + * <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> + +*/ diff --git a/Src/Utils/Site_dox/MainPage.dox b/Src/Utils/Site_dox/MainPage.dox new file mode 100644 index 000000000..87bcbbb80 --- /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: + * <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. + * + */ + + + -- GitLab