FExamples.dox 10.1 KB
Newer Older
1
/*! \page mainexamples Main Example	
2 3

 * \tableofcontents
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
 * \section The repositories structure

 * In the scalfmm directory, you can locate several folders and the directory structure is as follows:
 <ul>
 <li> Src       sources folder </li>
  <ul>
  <li>Arranger: ??</li>
  <li>Components: Basic components.</li>
  <li>Containers: The containers used in ScalFMM</li>
  <li>Core: The different kind of parallel algorithms: Threads means OpenMP (fork-join, task, ...) while Proc is for MPI.</li>
  <li>Extensions:  ??</li>
  <li>Files: our different loaders/wrtiters for particule (csvn vtk, FMA, ...)</li>
  <li>GroupTree: A grouped octreed used with runtime system to improve the granularity.</li>
  <li>Kernels: The different kernels available ins ScalFMM. One forlder per kernel. </li>
  <li>Utils: All classes used inside the Library that are not specific to the FFM method.</li>
  </ul>
  
 <li> Examples  Main drivers: distribution generation, FMM drivers (Rotation (1/r), Interpolation (Uniform and Chebyschev)</li>
  <li> Tests. Other examples (prototpes) to understand how you can use the different features of ScalFMM.</li>
  <li> UTests  unit tests (CTEST)</li> 
  <li> Addons  folder that contains one sub-folder per addon</li>
  <li> Doc the documentation directory use Doxygen to generate it)</li> 
 <li> Data folder which contains particles files or any other data needed per the simulation examples.</li>
  </ul>
 *
29 30 31 32 33 34 35 36 37 38 39 40 41 42
 * Here we focus mainly on the Tests and UTests folders, and we
 * encourage users to look directly in the code file to see how things
 * are made.

 * \section how How to use

 * \subsection parameters The parameters system

 * Most of the examples need some user parameters or let the user shows
 * some values. This is done with the FParameters class. You can open
 * an example and find the parameters directives, like in the
 * Tests/Utils/testStatsTree.cpp:

 \code{.cpp}
43
 const int NbLevels = FParameters::getValue(argc,argv,"-depth", 5);	
44

45
 const int SizeSubLevels = FParameters::getValue(argc,argv,"-subdepth", 3);
46 47 48 49 50 51 52

 const char* const filename = FParameters::getStr(argc,argv,"-f", "../Data/test20k.fma"); 
 \endcode

 * This means that in the console, you can tape: 

 \code{.cpp}
53
 ./Tests/Release/testStatsTree -depth [an height] -subdepth [a sub height] -f [a file to load]
54 55 56
 \endcode


COULAUD Olivier's avatar
COULAUD Olivier committed
57
 * \subsection concrete A Concrete example : Spherical Harmonics FMM
58

59 60
 * In this part we will run a simulation with Spherical Harmonics and rotation optimization:
 *  ./Examples/Release/RotationFMM .
61 62 63 64 65 66

 * \subsubsection create Create a particles file 

 In the test file we can read: 

 \code{.cpp}
COULAUD Olivier's avatar
COULAUD Olivier committed
67 68
 * std::string filename = FParameters::getStr(argc, argv,"-fin", "../Data/test20k.fma"); 
 * FFmaGenericLoader  loader(filename); 
69 70
 \endcode

COULAUD Olivier's avatar
COULAUD Olivier committed
71
 * It means, that the test file is reading FMA file (see <a href="class_f_fma_generic_loader.html#details">FMA format</a>)
72
 * which can be changed but here we still use this format. We can pass a
COULAUD Olivier's avatar
COULAUD Olivier committed
73 74
 * file in parameter with the -fin option. So let first create with <a href=generate_distributions_8cpp.html> generateDistributions</a> 2.000.000
 * particles in a unit cube and store the particle in a file with the FMA  format:
75 76

 \code{.cpp}
77
 * ./Examples/Release/generateDistributions -N 2000000 -unitcube -fout my2kkpartfile.fma 
78 79 80 81 82 83
 \endcode

 Which create a file called my2kkpartfile.fma. 

 * \subsubsection running Running the Simulation

COULAUD Olivier's avatar
COULAUD Olivier committed
84 85
 * With the Spherical harmonic expansion  kernel we can choose the P=4 accuracy parameter for this
 * kernel.  RotationFMM
86 87

 \code{.cpp}
COULAUD Olivier's avatar
COULAUD Olivier committed
88
 * ./Examples/Release/RotationFMM -f my2kkpartfile.fma -depth 5 -subdepth 3 
89 90
 \endcode

91

COULAUD Olivier's avatar
COULAUD Olivier committed
92
* \section driver Drivers
93 94 95
*   <a href="../html/files.html"> Here</a> some drivers.
*
html/files.html
96 97 98 99 100 101 102 103 104 105 106 107 108 109 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 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
 \section example_from_test Examples from Tests

 \subsection tests_utils From Tests/Utils

 <ul>
 <li> testACA.cpp : this file the ACA matrix operation. </li>
 <li> testLoaderCreate.cpp : this file creates a basic particles file in the basic format. </li>
 <li> testBlas.cpp : this file tests the blas, it simply validate that the link was OK </li>
 <li> testLoaderFMABinCreate.cpp : this file creates a particles file in binary in the FMA format.  </li>
 <li> testChebBinaryM2L.cpp :  </li>
 <li> testChebBinarySymM2L.cpp  </li>
 <li> testLoaderFMA.cpp : this file illustrates how to load particles from a FMA file.  </li>
 <li> testChebInterpolator.cpp :  </li>
 <li> testLoaderFMACreate.cpp: this file creates a particles text-file in the FMA format.  </li>
 <li> testChebM2Lprecomputation.cpp : </li>
 <li> testLoaderFMACreateSphere.cpp : this file creates particles text file in the FMA format with a spherical distribution.  </li>
 <li> testChebOctree.cpp : this file illustrates how to use the octree.  </li>
 <li> testLoaderFMATsm.cpp : this load an FMA file with targets != sources.  </li>
 <li> testChebSxUCBSy.cpp  </li>
 <li> testLoaderFMATsmCreate.cpp : this create a particles text file with targets != sources </li>
 <li> testChebSymmetries.cpp </li>
 <li> testMemStats.cpp : this shows how to use the memory stats. </li>
 <li> testChebTensorProduct.cpp:  </li>
 <li> testMortonIndex.cpp: this is an example of the Morton index usage and conversion.  </li>
 <li> testCompareIOTree.cpp : this loads two octrees and compare them.  </li>
 <li> testDebug.cpp : to illustrate how to use the debug macro and controller </li>
 <li> testOctree.cpp : to show how to use the octree.  </li>
 <li> testFmmAlgorithm.cpp : this runs the FMM algorithm with the test set.  </li>
 <li> testOctreeIter.cpp : shows how to iterate on the octree.  </li>
 <li> testFmmAlgorithmPeriodic.cpp : this runs the FMM algorithm with the test set and periodic set to ON.  </li>
 <li> testOctreePrintMorton.cpp : to knows every thing about the Morton index of an octree.  </li>
 <li> testFmmAlgorithmProc.cpp : this runs the FMM algorithm with the test set and MPI.  </li>
 <li> testOctreeRearrange.cpp : this runs the FMM algorithm with the test set and rearrange the particles.  </li>
 <li> testFmmAlgorithmProcPeriodic.cpp : this runs the FMM algorithm with the test set, MPI and periodicity.  </li>
 <li> testOctreeRearrangeProc.cpp : this runs the FMM algorithm with the test set and rearrange the data with MPI.  </li>
 <li> testFmmAlgorithmTsm.cpp : this runs the FMM algorithm with the test set and sources != targets.  </li>
 <li> testStatsTree.cpp : this gives some information about an octree.  </li>
 <li> testFmmDemonstration.cpp:  </li>
 <li> testTic.cpp: shows how to use the timer.  </li>
 <li> testLoader.cpp : this uses a basic loader.  </li>
 <li> testTreeIO.cpp : this stores and restore an octree on hard drive. </li>
 </ul>

 * \subsection tests_kernels From Tests/Kernels

 <ul>
 <li> testChebAlgorithm.cpp : this runs the Chebyshev FMM. </li>
 <li> testFlopsChebAlgorithm.cpp : this counts the flops in the Chebyshev FMM. </li>
 <li> testRotationAlgorithm.cpp : this runs the Rotation FMM.</li> 
 <li> testSphericalBlockBlasAlgorithm.cpp : this runs the SH FMM with blocked blas. </li>
 <li> testSphericalEwalAlgorithm.cpp : this runs the SH FMM and compare with an ewal summation. </li> 
 <li> testSphericalGalaxyCsv.cpp : this runs the SH FMM output an csv file to visualize in Paraview. </li>
 <li> testSphericalProcAlgorithm.cpp : this runs the SH FMM with MPI. </li>
 <li> testSphericalRotationAlgorithm.cpp : this runs the SH FMM with rotation. </li>
 <li> testSphericalTsmAlgorithm.cpp : this runs the SH FMM with targets != sources. </li>
 <li> testSphericalAlgorithm.cpp : this runs the SH FMM. </li>
 <li> testSphericalTsmNoTsm.cpp : this runs the SH FMM with targets != sources. </li>
 <li> testSphericalBench.cpp : this runs the SH FMM and perform some bench. </li>
 <li> testTuneSphericalBlockBlas.cpp : this runs the SH FMM and shows different results for the size of the block. </li>
 <li> testSphericalBlasAlgorithm.cpp : this runs the SH FMM with blas. </li>
 <li> testCompareKernels.cpp : this runs compare several kernels. </li>
 </ul>

 \section examples_from_Utest Examples from UTests

 * In this folder you will find the unit tests. There are some related to
 * data structures (like vector or list) and some others related to real
 * FMM.

 <ul>

 <li> FUTester.hpp : this is the main class for unit test.  </li>
 <li> utestParameters.cpp : this tests the FParameters class which allow a quick access to application command line parameter.  </li>
 <li> utestQuicksort.cpp : this tests the quick sort in sequential and shared memory.  </li>
 <li> utestRotationDirect.cpp : this tests the rotation FMM.  </li>
 <li> utestBoolArray.cpp : this tests the boolean array which is a data structure that enable bit bool value.  </li>
 <li> utestRotationDirectPeriodic.cpp : this tests the rotation kernel with periodicity.  </li>
 <li> utestBuffer.cpp : this tests the buffer used in the serialization of data in the MPI FMM.  </li>
 <li> utestSphericalDirect.cpp : this tests the Spherical Harmonic kernel.  </li>
 <li> utestChebyshevDirect.cpp : this tests the Chebyshev kernel.  </li>
 <li> utestSphericalDirectPeriodic.cpp : this tests the Chebyshev kernel with periodicity.  </li>
 <li> utestChebyshevDirectPeriodic.cpp : this tests the Spherical Harmonic kernel with periodicity.  </li>
 <li> utestSphericalWithPrevious.cpp : this tests the Spherical Harmonic kernel with a previous run.  </li>
 <li> utestList.cpp : this tests our home made linked list.  </li>
 <li> utestTest.cpp : this tests the unit test main class (this is just an example of how to use).  </li>
 <li> utestMorton.cpp : this tests the Morton indexing tools.  </li>
 <li> utestVector.cpp : this tests our home made vector.  </li>
 <li> utestOctree.cpp : this tests the octree validation.	 </li>
 </ul>

BRAMAS Berenger's avatar
BRAMAS Berenger committed
186 187 188 189 190 191 192
 * \section makeyourown Create your own application using ScalFMM
 * In you compile ScalFMM and enabled the Tests (by passing a parameter to CMake or by using ccmake)
 * any cpp file that will put into the Tests/ directories will be compiled and linked to ScalFMM.
 * Therefore it can be a quick way to create and test with scalfmm without creating your own project and
 * thinking about the compilation and link stages.
 * Put your file in the test directories, enable the Tests in the cmake, be sure that the CMake is generated (type cmake.. again
 * in the build dir), and then make your_cpp_file_without_extension
193
*/