From e4e79ad0d6e252a6bc4f32c5c6fb27b33f5b2ded Mon Sep 17 00:00:00 2001
From: Denis Davydov <davydden@gmail.com>
Date: Fri, 27 Jan 2017 13:16:12 +0100
Subject: [PATCH] explicitly mention Spherical-Cartesian transformation

---
 include/deal.II/base/geometric_utilities.h | 18 ++++++++++++++++--
 source/base/geometric_utilities.cc         |  4 ++--
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/include/deal.II/base/geometric_utilities.h b/include/deal.II/base/geometric_utilities.h
index 2dc55c40b2..76b4d9a6a6 100644
--- a/include/deal.II/base/geometric_utilities.h
+++ b/include/deal.II/base/geometric_utilities.h
@@ -45,6 +45,13 @@ namespace GeometricUtilities
      * Return spherical coordinates of a Cartesian point @p point.
      * The returned array is filled with radius, azimuth angle $\in [0,2 \pi)$
      * and polar/inclination angle $ \in [0,\pi]$ (ommited in 2D).
+     *
+     * In 3D the transformation is given by
+     * @f{align*}
+     *  r &= \sqrt{x^2+y^2+z^2} \\
+     *  \theta &= {\rm atan}(y/x) \\
+     *  \phi &= {\rm acos} (z/r)
+     * @f}
      */
     template <int dim>
     std_cxx11::array<double,dim>
@@ -52,9 +59,16 @@ namespace GeometricUtilities
 
     /**
      * Return the Cartesian coordinates of a spherical point defined by @p scoord
-     * which is filled with radius $\in [0,\infty)$, azimuth angle
-     * $\in [0,2 \pi)$ and polar/inclination angle $\in [0,\pi]$
+     * which is filled with radius $r \in [0,\infty)$, azimuth angle
+     * $\theta \in [0,2 \pi)$ and polar/inclination angle $\phi \in [0,\pi]$
      * (ommited in 2D).
+     *
+     * In 3D the transformation is given by
+     * @f{align*}
+     *  x &= r\, \cos(\theta) \, \sin(\phi) \\
+     *  y &= r\, \sin(\theta) \, \sin(\phi) \\
+     *  z &= r\, \cos(\phi)
+     * @f}
      */
     template <std::size_t dim>
     Point<dim>
diff --git a/source/base/geometric_utilities.cc b/source/base/geometric_utilities.cc
index 427cdf2ca5..d136537cd4 100644
--- a/source/base/geometric_utilities.cc
+++ b/source/base/geometric_utilities.cc
@@ -47,13 +47,13 @@ namespace GeometricUtilities
 
       // radius
       scoord[0] = position.norm();
-      // azimuth angle
+      // azimuth angle \theta:
       scoord[1] = std::atan2(position(1),position(0));
       // correct to [0,2*pi)
       if (scoord[1] < 0.0)
         scoord[1] += 2.0*numbers::PI;
 
-      // polar angle
+      // polar angle \phi:
       if (dim==3)
         {
           // acos returns the angle in the range [0,\pi]
-- 
2.39.5