Force Algorithm with Complexity O(N): a users guide

CONTENTS

1. Overview
2. Guarantee
3. Compiler options
4. Installation
5. Use of the code
6. Some tips for using the code
7. About bugs

1. OVERVIEW

   The code falcON described here is not a N-body code, but merely a package for computing the accelerations (and some other things, too), which can be used as Poisson solver in your existing N-body code.

2. GUARANTEE

   This package comes with absolutely no guarantee whatsoever! The unpacking, compiling, and using of the code is entirely at the risk of the user alone.

3. COMPILER OPTIONS

   Before running make, you may want arrange for some non-default settings that control certain code features as follows.
   • Floating point precision
     There two issues here: the floating point precision internal to the code and that used in array arguments for communicating the data (positions, accelerations, etc) with the code via arrays (rather than bodies), which is the only option for C and FORTRAN users. These two precisions may be different. You can choose by setting the compiler macro PRECISION in file make.falcON as follows.
     
     PRECISION := SINGLE_SINGLE # internal: 32 bit, arrays: 32 bit (default)
     PRECISION := SINGLE_DOUBLE # internal: 32 bit, arrays: 64 bit
     PRECISION := DOUBLE_SINGLE # internal: 64 bit, arrays: 32 bit
     PRECISION := DOUBLE_DOUBLE # internal: 64 bit, arrays: 64 bit
     
     I know of no case where internal 64bit precision was necessary and/or equally fast as 32bit.
     
     
   • Mutual softening length
     In case of individual softening lengths e_i the softening length e_ij used in an interaction between two bodies is some symmetrical function of the individual softening lengths e_i and e_j. There are two options, controlled by the makefile macro SOFTENING in file make.falcON:
     
     SOFTENING := SOFT_MIN # e_ij = min(e_i,e_j)
     SOFTENING := SOFT_MEAN # e_ij = the mass-weighted mean of e_i, e_j (default)
     
     
   • NEMO I/O support
     The data I/O from bodies (file inc/body.h) may be done in the hardware independent NEMO format. This possibility is activated if, at compilation time, NEMO has been activated, i.e. if the enviroment variable NEMO is defined (we also need NEMOINC, NEMOLIB and NEMOVER).

4. INSTALLATION

   The installation is best done with GNU make (the makefiles provided don't work for, e.g., Solaris make) and using the GNU gcc compiler. I used gcc version 2.95.2. I also tried version 3.0, but I only managed to produce larger and slower code (and compilation took longer). The making takes a little while but should not produce any warning or error messages. Otherwise something might be wrong. To generate a library, type "make falcON", which creates the library lib/libfalcON.a. A two-dimensional version (not tested) can be created by typing instead "make falcON2D", which creates the library lib/libfalcON2D.a.

5. USE OF THE CODE

   As to the proper values of the various parameters (softening and tolerance parameter) you are strongly advised to carefully read the notes of caution .

   • With C++
     In order to make use of the code, you need to insert
     #include <falcON.h>
     somewhere at the beginning of your C++ source code. Make sure that the compiler finds the file falcON.h by including "-I FALCON/inc" among your compiler options. The usage of the code in your application is explained in gory detail in the file falcON.h (do'nt forget that flacON lives in namespace nbdy). In order to make an executable you also need to add the appropriate linker option for the library. These are "-L FALCON/lib -lfalcON -lm" for the 3D version and "-L FALCON/lib -lfalcON2D -lm" for the 2D version. Of course, you only need to make the library you actually want to use. For examples of code using falcON.h, see the files src/C++/TestGrav.cc and src/C++/TestPair.cc, which may be compiled by typing "make TestGrav" and "make TestPair" and produce a short summary of their usage when run without arguments.

   • With C
     In order to make use of the code, you need to insert
     #include <falcON_C.h>
     somewhere at the beginning of your C source code. Make sure that the compiler finds the file falcON_C.h by including "-I FALCON/inc" among your compiler options. The usage of the code in your application is explained in gory detail in the file falcON_C.h. In order to make an executable you also need to add the appropriate linker option for the library. These are "-L FALCON/lib -lfalcON -lstdc++ -lm" for the 3D version and "-L FALCON/lib -lfalcON2D -lstdc++ -lm" for the 2D version. Of course, you only need to make the library you actually want to use. For examples of code using falcON_C.h, see the files src/C++/TestGravC.cc and src/C++/TestPairC.cc, which may be compiled by typing "make TestGravC" and "make TestPairC" and produce a short summary of their usage when run without arguments.

   • With FORTRAN
     In order to make use of the code, you need to insert
     INCLUDE 'falcON.f'
     somewhere at the beginning of your FORTRAN program. Make sure that the compiler finds the file falcON.f by including "-I FALCON/inc" among your compiler options. The usage of the code in your application is explained in gory detail in the file falcON.f. In order to make an executable you also need to add the appropriate linker option for the library. These are "-L FALCON/lib -lfalcON -lstdc++ -lm" for the 3D version and "-L FALCON/lib -lfalcON2D -lstdc++ -lm" for the 2D version. Of course, you only need to make the library you actually want to use. For examples of code using falcON.f, see the files src/C++/TestGravF.cc and src/C++/TestPairF.cc, which may be compiled by typing "make TestGravF" and "make TestPairF". Just run these code, they are self-explanatory and provide some statistics output. You may also use the input files given and run them as "TestGravF < treeF.in" and "TestPairF < pairF.in".
     
     NOTE THAT FOR REASONS I DONT UNDERSTAND THE FORCE SUM DOES NOT VANISH IN THE FORTRAN VERSION OF TESTGRAV, EVEN THOUGH THE INDIVIDUAL FORCES ARE IDENTICAL TO THOSE OF THE C AND C++ VERSION, FOR WHICH THE FORCE SUM DOES VANISH (WITHIN FLOATING POINT ACCURACY). Any help with this question is most welcome (something to do with C <-> FORTRAN data transfer ???).

6. SOME TIPS ABOUT USING THE CODE

   • Replacing PP in PP-PM codes In so-called P^3M codes used for cosmological simulations, gravity is computed with periodic boundary conditions employing a FFT-based Poisson solver on some grid (PM=particle-mesh). Whenever structures form that can no longer be resolved with the grid, the forces generated withing these structures are computed using either direct summation (P^2=particle-particle). Here, we describe how falcON can be used to replace the P^2 part.
     We propose to initialize falcON with all N bodies in the simulation. Then, whenever the forces within one sub-structure shall be approximated by falcON, flag all bodies not belonging to this structure to be ignored by falcON (set bit 2 of the flag array, see falcON.h, falcON_C.h, or falcON.f) then grow() the tree (do not re-use!). Now any call of falcON::approximate_gravity() (FALCON_APPROX_GRAV() for FORTRAN or falcON_approx_grav() for C) computes the forces generated by all bodies belonging to the sub-structure (not flagged to be ignored) on all bodies of the sub-structure that are additionally flagged to be sink. If you always want all bodies to be sink, you only need to set & re-set the flag indicating usage.

7. ABOUT BUGS

   Each of the files falcON.h, falcON_C.h, and falcON.f, contains a little section about known bugs. If you think you found another bug, please send me a bug report. Thanks.

Have Fun!