Laguerre Spherical Harmonic Transform
======================================
Version 1.x

Download as Guest
git clone https://gitlab.in2p3.fr/campagne/LagSHT.git

	
# List of files
* 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_testsuite.c : a simple program to test different piece of the code
* Makefile that should be tuned to the local platform (*.inc files)
* doxydoc / footer.html : input file to doxygen tool to generate the class documentation 

# Required Librairy

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

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

	sharp_geom_info* get_geom_info() { return ginfo;} 
	sharp_alm_info*  get_alm_info()  { return ainfo; }
	
* OpenBLAS (see note Darwin below): 

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
`git clone https://github.com/xianyi/OpenBLAS.git`	
**WARNING**: on Darwin the Makefile use the `Accelerate Framework` features which are a bit more effective than OpenBLAS.

*  ANN (under test) :
ANN is a library written in C++, which supports data structures and algorithms for both exact and approximate nearest neighbor searching in arbitrarily high dimensions. It is distributed under the terms of the GNU Lesser Public License. The code require an ANSII C++ and is tested under different platforms. I have build it using g++ compilor on Mac OS X which was not mentionned by the author. ANN is used to perform to find the closest pixel index given the (theta, phi) position of a point.


# Compilation
 	> edit Makefile and adapat to local platform :
 		1) adapt to the type of Machine MacOSX (Darwin) vs Linux
 		2) adapt the location of the libsharp library (SHARPDIR) 
 		3) on Linux adapt the location of BLAS/OpenBLAS 
 		4) then the make depends on the plateform and if you have BLAS
```
> make MACH=Linux BLAS=1 : on Linux with BLAS ON  
> make  : (default) on Darwin and use Accelerate Framework
```
 	> make check
 		runs a computation of the Nodes & Weights for N=1024
 		 and compare to the xxx.txt.TEST files to produce a
 		 Numerical Error estimate.
# Plateform tested
	Mac OS X 10.9.5 + gcc 4.8.4
	Linux SLC 6.6   + gcc 4.9.1 20140922

# 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)
		3: to test the full 3D Spherical Harmonic Laguerre trabsform (Synthesis & Analysis) 
	> <geometry>
		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 Nside parameter.
	> 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. 	
	

# Examples
* ./Objs/lagsht_testsuite -n 1024
   gives 2 files `lagNodes-1024-Func.txt` and `lagWeights-1024-Func.txt` with the Nodes & Weights computed
* ./Objs/lagsht_testsuite -t 3 -l 1024 -n 128
   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). 

````
./Objs/lagsht_testsuite -t 3 -l 1024 -n 128
Max Memory size: 8589 MBytes
 ___________  MultiSphericalLaguerreTransform   TEST _____________ 
LaguerreTransform start....
Sum roots = 16640 -> diff with theory: -5.68434e-14
Sum weights = 0.657058 -> diff with theory: 1.79737e-13
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....
Error analysis...
(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)
 >>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<
Err. Max. 2.30169e-11 [9469597], Err. Rel. 3.35703e-08
 >>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<

Total wall clock time for 'MultiSphericalLaguerreTransform': 29.8856s
|
+- processing                     : 92.03% (27.5048s)
|  |
|  +- processing part Analysis       : 53.07% (14.5966s)
|  |  |
|  |  +- SHT Analysis                   : 85.80% (12.5241s)
|  |  +- Laguerre MultiAnalysis         :  5.41% ( 0.7890s)
|  |  +- <unaccounted>                  :  8.79% ( 1.2835s)
|  |  
|  +- processing part Synthesis      : 46.93% (12.9082s)
|  |  |
|  |  +- SHT Synthesis                  : 84.97% (10.9686s)
|  |  +- Laguerre MultiSynthesis        :  4.84% ( 0.6242s)
|  |  +- <unaccounted>                  : 10.19% ( 1.3155s)
|  |  
|  +- <unaccounted>                  :  0.00% ( 0.0000s)
|  
+- data input                     :  3.24% ( 0.9683s)
+- <unaccounted>                  :  4.73% ( 1.4125s)


Accumulated timing overhead: approx. 0.0000s

```