Main Examples

Table of Contents

• repositories structure
• How to use
  • The parameters system
  • A Concrete example : Spherical Harmonics FMM
    • Create a particles file
    • Running the Simulation
• Drivers
  • From Examples repository
• Examples from Tests
  • From Tests/Utils
  • From Tests/Kernels
• Examples from UTests
• Create your own application using ScalFMM

repositories structure

In the scalfmm directory, you can locate several folders and the directory structure is as follows:

• Src sources folder

  • Arranger:
  • Components: Basic components.
  • Containers: The containers used in ScalFMM
  • Core: The different kind of parallel algorithms: Threads means OpenMP (fork-join, task, ...) while Proc is for MPI.
  • Extensions: classes or methods to extend the FMM.
  • Files: our different loaders/wrtiters for particule (csvn vtk, FMA, ...)
  • GroupTree: A grouped octreed used with runtime system to improve the granularity.
  • Kernels: The different kernels available ins ScalFMM. One forlder per kernel.
  • Utils: All classes used inside the Library that are not specific to the FFM method.

• Examples Main drivers: distribution generation, FMM drivers (Rotation (1/r), Interpolation (Uniform/Lagrange and Chebyschev)
• Tests. Other examples (prototpes) to understand how you can use the different features of ScalFMM.
• UTests unit tests (CTEST)
• Addons folder that contains one sub-folder per addon
• Doc the documentation directory use Doxygen to generate it)
• Data folder which contains particles files or any other data needed per the simulation examples.

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.

How to use

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:

const int NbLevels = FParameters::getValue(argc,argv,"-depth", 5);     
 
const int SizeSubLevels = FParameters::getValue(argc,argv,"-subdepth", 3);
 
const char* const filename = FParameters::getStr(argc,argv,"-f", "../Data/test20k.fma"); 

This means that in the console, you can tape:

./Tests/Release/testStatsTree -depth [an height] -subdepth [a sub height] -f [a file to load]

A Concrete example : Spherical Harmonics FMM

In this part we will run a simulation with Spherical Harmonics and rotation optimization: ./Examples/Release/RotationFMM .

Create a particles file

In the test file we can read:

std::string filename = FParameters::getStr(argc, argv,"-fin", "../Data/test20k.fma"); 
FFmaGenericLoader  loader(filename); 

It means, that the test file is reading FMA file (see FMA format) which can be changed but here we still use this format. We can pass a file in parameter with the -fin option. So let first create with generateDistributions 2.000.000 particles in a unit cube and store the particle in a file with the FMA format:

./Examples/Release/generateDistributions -N 2000000 -unitcube -fout my2kkpartfile.fma 

Which create a file called my2kkpartfile.fma.

Running the Simulation

With the Spherical harmonic expansion kernel we can choose the P=4 accuracy parameter for this kernel. RotationFMM

./Examples/Release/RotationFMM -f my2kkpartfile.fma -depth 5 -subdepth 3 

Drivers

From Examples repository

• DirectComputation Direct computation between particles (N^2 algorithm).
• ChebyshevInterpolationFMM FMM on Chebyshev grid points.
• LagrangeInterpolationFMM FMM on equispaced grid points
• ChebyshevInterpolationMPIFMM MPI-FMM on Chebyshev grid points..
• RotationFMM FMM with spherical harmonics expansion with rotation.
• RotationMPIFMM MPI-FMM with spherical harmonics expansion with rotation..
• generateDistributions driver to generate particles distribution.
• CutOffAlgorithm Cutoff algorithm.

• changeFmaFormat driver to manage our input/output format..

Examples from Tests

From Tests/Utils

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

From Tests/Kernels

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

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.

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

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