README.md 8.44 KB
Newer Older
1
Laguerre Spherical Harmonic Transform
2
======================================
3
Version 1.x (last update of this file 7/10/15)
4

5 6 7 8
Main Author: J.E Campagne - Lab. Accelerateur Lineaire - CNRS/IN2P3 & PARIS-SUD University - France
	
Contributor: M. Reinecke - Max-Planck Institute for Astrophysics - Garching - Germany
	
9
Download as Guest
10 11
git clone https://gitlab.in2p3.fr/campagne/LagSHT.git

12 13
	
# List of files
14 15 16 17 18 19 20 21 22 23
* **src** directory
	* laguerreBuilder.h (.cc) : class of generalized Laguerre function 
	* laguerreTransform.h (.cc) : class to manage the Laguerre function Transform (Synthesis & Analysis): Single or Multiple  
	* lagSphericTransform.h (.cc) : class to manage the Spherical Harmonic & Laguerre function Trnasform (Synthesis & Analysis). Choice of different geometry for the Sphere pixelizations.
	* lagsht_execptions.h: class derived from std::exceptions.
	* walltimer.h (.cc): utilities to profile the program.
	* lagsht_utils.h: code by David Robert Nadeau to get the avalable memory
	* lagsht_spheregeom.h (.cc) : set of classes to deeal with the 2D sphere pixelization and libsharp initialization
	* lagsht_geom.h : define some typedef used in the code for geometry
	* lagsht_testsuite.c : a simple program to test different piece of the code
24 25 26
	* laguerre2bessel.h (.cc) : implement the computation of Fourier-Bessel transform from Fourier-Laguerre coeff.
	* lagsht_bessel.h (.cc) : simple Bessel class (use Boost)
	* quadinteg.h : Quadrature integration and strategy 
27
* **root** directory 
28
	* Makefile that should be tuned to the local platform (*.inc files)
29
* **doc** directory 
30 31
	* doxydoc : input file to `doxygen` tool to generate the class documentation 
* **bin**/**lib** directories are the location of executable and library while **include** is the location of LagSHT/*.h files.
32 33 34
* **trest** director
	* test3D.cc : this is a series of test functions (as in lagsht_testsuite.cc) but related to some 3D analysis with Cl-like spectra : Cl(k) with k a shell index a la CMB, and Cl(n) which are computed from the Fourier-Laguerre flmn coefficients. 
	* test3D-xy.txt are the outputs of the tests on my machine (Mac OSX).
35

36
# Required Librairy
37

38
* LIBSHARP :
39
`git clone git://git.code.sf.net/p/libsharp/code libsharp-code`
40

41
Look at the `libsharp-code/libsharp/sharp_cxx.h` file and add if necessary 
42

43 44
	sharp_geom_info* get_geom_info() { return ginfo;} 
	sharp_alm_info*  get_alm_info()  { return ainfo; }
45
	
46
* OpenBLAS (see note Darwin below): 
47

48
If the variable `CBLAS` is defined then the code of laguerreTransform.cc use the BLAS matrix multiplication highly optimized. See installation in the Readme.md using
49 50
`git clone https://github.com/xianyi/OpenBLAS.git`
	
51
**WARNING**: on Darwin the Makefile use the `Accelerate Framework` features which are a bit more effective than OpenBLAS.
52

53 54 55
* Boost (version >= 1.58):

This is simply header files which are needed to access to the `"boost/math/special_functions/bessel.hpp"` and related headers of the library.
56

57
# Compilation
58 59 60 61 62 63 64
1. edit Makefile and adapat to local platform :
	
	* adapt to the type of Machine MacOSX (Darwin) vs Linux
	* adapt the location of the libsharp library (SHARPDIR) 
 	* on Linux adapt the location of BLAS/OpenBLAS 
 	* also update the **LD\_LIBRARY\_PATH** to get the OpenBLAS shared library avaliable at run time:

65 66 67
 			csh> setenv LD_LIBRARY_PATH <dir>/OpenBLAS/lib:${LD_LIBRARY_PATH}
 			bassh> LD_LIBRARY_PATH=<dir>/OpenBLAS/lib:${LD_LIBRARY_PATH}; export $LD_LIBRARY_PATH
 			 
68 69 70 71 72 73 74 75 76 77 78 79
2. Then the make depends on the plateform and if you have BLAS

	* make MACH=Linux BLAS=1 : on Linux with BLAS ON  
	* make  : (default) :
		 - will select the system thanks tu uname shell function: if on Linux + No BLAS, if on Darwin use Accelerate 
   		Framework.
   	
   	The result of "make" is binanry file under ./bin directory as well as `lagsht.a` library in ./lib

3. make check

	It runs a computation of the Nodes & Weights for N=1024
80 81
 		 and compare to the xxx.txt.TEST files to produce a
 		 Numerical Error estimate.
82 83 84 85 86 87 88 89 90

4. make fullcheck 
 
 	It runs a series of `lagsht_testsuite` which activates different parts of the code and shows how-to call this test program.

5. make install
	* install the \<root\>/src/headers files to  \<root\>/include/LagSHT 
	* then one should use -I<root>/include/LagSHT in their makefile. 
	* If one wants a different location then look at INCL variable 
91 92 93 94
 		in the Makefile. 
 		Similarly, the library is in <root>/lib but one can switch to 
 		another location by modifying the LIB variable in the 
 		Makefile.	  
95

96 97 98
# Plateform tested
	Mac OS X 10.9.5 + gcc 4.8.4
	Linux SLC 6.6   + gcc 4.9.1 20140922
99

100 101 102 103 104 105 106 107 108 109 110
# Running
	> ./Objs/lagsht_testsuite -t <test number> [1]
		[-n <Nmax value> [5]] [-l <Lmax value> [10]] 
		[-g <geometry> Gauss|Fejer1|Healpix [Gauss]]
		[-ntheta <number of theta rings> [determined by the geometry]
			in case of Healpix gives the nside parameter]
		 [-nphi <number of pixel per rings> [determined by the geometry]]	
	> <test number>: 
		0: basic test for numerical application
		1: to get the nodes & weights of the generalized Gauss-laguerre function quadrature.
		2: to test 1D- Laguerre Transform (Synthesis & Analysis)
111 112
		3: to test 2D- pixelization schemes from libsharp 
		4: to test the full 3D Spherical Harmonic Laguerre trabsform (Synthesis & Analysis) 
113
		5: to test the Laguerre -> Bessel transform 
114
	> <geometry>
115 116 117 118 119 120 121 122
		Gauss : use the Gauss quadrature by default Ntheta = Lmax and
		 Nphi = 2Lmax - 1. 
		
		Fejer1: use the Fejer's sum rule n°1 by default 
		Ntheta = 2Lmax-1 and Nphi = 2Lmax-1. 
		
		Healpix: use the Healpix map with Ntheta giving the Nsides
		 parameter.
123 124
	> nphi: libsharp works faster if this number is increased (compared to the minimal number required by the geometry) up to a power of 2 number. Eg. for Lmax = 1024, Nphi_min = 2L-1 = 2047, so Nphi = 2048 will run faster. 	
	
125

126 127 128
# Examples
* ./Objs/lagsht_testsuite -n 1024
   gives 2 files `lagNodes-1024-Func.txt` and `lagWeights-1024-Func.txt` with the Nodes & Weights computed
129
* ./Objs/lagsht_testsuite -t 4 -l 1024 -n 128
130
   perform a Laguerre SH transform with the default geometry (Gauss) using Lmax = 1024 and Nmax = 128. The program generates a set of flmn coefficients, then performs a Synthesis followed by an Analysis operations. Finally it computes the maximal absolute and relative errors comparing the original flmn complex values to the results of the Analysis. The timing of the different processes is shown in a sorted tree (here on Darwin Mac Os X with Accelerate Framework). 
131 132

````
133
./Objs/lagsht_testsuite -t 4 -l 1024 -n 128
134 135 136
Max Memory size: 8589 MBytes
 ___________  MultiSphericalLaguerreTransform   TEST _____________ 
LaguerreTransform start....
137 138
Sum roots = 16640 -> diff with theory: -5.68434e-14
Sum weights = 0.657058 -> diff with theory: 1.79737e-13
139 140 141 142 143
SetThetaPhiMap: Geom, Nring, Nphi, Npix, Nalm: Gauss, 1024, 2047, 2096128, 524800
Main:Synthesis r_8 function...
Multi Synthesis with Function....:128
Main:Analysis r_8 function...
Analysis with Function....
144
Error analysis...
145 146 147 148 149 150 151 152
(67174392) : flnm Orig (0.510484,0.108741) <-> flmn Rec (0.510484,0.108741)
(67174393) : flnm Orig (0.251975,0.463983) <-> flmn Rec (0.251975,0.463983)
(67174394) : flnm Orig (-0.163502,0.326319) <-> flmn Rec (-0.163502,0.326319)
(67174395) : flnm Orig (0.47971,0.771774) <-> flmn Rec (0.47971,0.771774)
(67174396) : flnm Orig (-0.748916,0.0658513) <-> flmn Rec (-0.748916,0.0658513)
(67174397) : flnm Orig (0.0890389,-0.589733) <-> flmn Rec (0.0890389,-0.589733)
(67174398) : flnm Orig (-0.16129,0.314123) <-> flmn Rec (-0.16129,0.314123)
(67174399) : flnm Orig (0.386101,0.876158) <-> flmn Rec (0.386101,0.876158)
153
 >>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<
154
Err. Max. 2.30169e-11 [9469597], Err. Rel. 3.35703e-08
155
 >>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<
156

157
Total wall clock time for 'MultiSphericalLaguerreTransform': 29.8856s
158
|
159
+- processing                     : 92.03% (27.5048s)
160
|  |
161
|  +- processing part Analysis       : 53.07% (14.5966s)
162
|  |  |
163 164 165
|  |  +- SHT Analysis                   : 85.80% (12.5241s)
|  |  +- Laguerre MultiAnalysis         :  5.41% ( 0.7890s)
|  |  +- <unaccounted>                  :  8.79% ( 1.2835s)
166
|  |  
167
|  +- processing part Synthesis      : 46.93% (12.9082s)
168
|  |  |
169 170 171
|  |  +- SHT Synthesis                  : 84.97% (10.9686s)
|  |  +- Laguerre MultiSynthesis        :  4.84% ( 0.6242s)
|  |  +- <unaccounted>                  : 10.19% ( 1.3155s)
172 173 174
|  |  
|  +- <unaccounted>                  :  0.00% ( 0.0000s)
|  
175 176
+- data input                     :  3.24% ( 0.9683s)
+- <unaccounted>                  :  4.73% ( 1.4125s)
177 178


179
Accumulated timing overhead: approx. 0.0000s
180

181
```