Merge branch 'master' of git+ssh://scm.gforge.inria.fr//gitroot//scalfmm/scalfmm

Src/Utils/FSpherical.hpp

 // ===================================================================================
-// Copyright ScalFmm 2011 INRIA, Olivier Coulaud, Bérenger Bramas, Matthias Messner
+// Copyright ScalFmm 2011 INRIA, Olivier Coulaud, Bérenger Bramas, Matthias Messner
 // olivier.coulaud@inria.fr, berenger.bramas@inria.fr
 // This software is a computer program whose purpose is to compute the FMM.
 //
@@ -26,26 +26,40 @@
 *
 * @brief Spherical coordinate system
 *
-* The spherical coordinate system (r radius, theta inclination, phi azimuth) is the following <br>
-* x = r sin(theta) cos(phi) <br>
-* y = r sin(theta) sin(phi) <br>
-* z = r cos(theta) <br>
+* We consider the spherical coordinate system \f$(r, \theta, \varphi)\f$ commonly used in physics. r is the radial distance, \f$\theta\f$ the polar/inclination angle and \f$\varphi\f$ the azimuthal angle.<br>
+* The <b>radial distance</b> is the Euclidean distance from the origin O to P.<br>
+* The <b>inclination (or polar angle) </b>is the angle between the zenith direction and the line segment OP.<br>
+* The <b>azimuth (or azimuthal angle)</b> is the signed angle measured from the azimuth reference direction to the orthogonal projection of the line segment OP on the reference plane.<br>
+*
+* The spherical coordinates of a point can be obtained from its Cartesian coordinates (x, y, z) by the formulae
+* \f$ \displaystyle r = \sqrt{x^2 + y^2 + z^2}\f$<br>
+* \f$ \displaystyle \theta = \displaystyle\arccos\left(\frac{z}{r}\right) \f$<br>
+* \f$ \displaystyle \varphi = \displaystyle\arctan\left(\frac{y}{x}\right) \f$<br>
+*and \f$\varphi\in[0,2\pi[ \f$ \f$ \theta\in[0,\pi]\f$<br>
+*
+* The spherical coordinate system  is retrieved from the the spherical coordinates by <br>
+* \f$x = r \sin(\theta) \cos(\varphi)\f$ <br>
+* \f$y = r \sin(\theta) \sin(\varphi)\f$ <br>
+* \f$z = r \cos(\theta) \f$<br>
+* with  \f$\varphi\in[-\pi,\pi[ \f$ \f$ \theta\in[0,\pi]\f$<br>
+*
 * This system is defined in p 872 of the paper of Epton and Dembart, SIAM J Sci Comput 1995.<br>
 *
 * Even if it can look different from usual expression (where theta and phi are inversed),
 * such expression is used to match the SH expression.
+*  See http://en.wikipedia.org/wiki/Spherical_coordinate_system
 */
 class FSpherical {
     // The attributes of a sphere
-    FReal r;         //!< the radius
+    FReal r;         //!< the radial distance
     FReal theta;     //!< the inclination angle [0, pi] - colatitude
-    FReal phi;       //!< the azimuth angle [-pi,pi] - longitude - around z axis
+    FReal phi;       //!< the azimuth angle [-pi,pi]$` - longitude - around z axis
     FReal cosTheta;
     FReal sinTheta;
 public:
     /** Default Constructor, set attributes to 0 */
     FSpherical()
-        : r(0), theta(0), phi(0), cosTheta(0), sinTheta(0) {
+        : r(0.0), theta(0.0), phi(0.0), cosTheta(0.0), sinTheta(0.0) {
     }
 
     /** From now, we just need a constructor based on a 3D position */
@@ -80,9 +94,10 @@ public:
     FReal getInclination() const{
         return theta;
     }
-    /** Get the azimuth angle [0,2pi] */
+    /** Get the azimuth angle [0,2pi]. You should use this method in order to obtain (x,y,z)*/
     FReal getAzimuth() const{
-        return (phi < 0 ? FMath::FPi*2 + phi : phi);
+       // return (FMath::FPi + phi );
+        return (phi < 0 ? FMath::FPi*2.0 + phi : phi);
     }
 
     /** Get the cos of theta = z / r */