Added more documentation.

Removed a bug in the CartSphere transformation (for r,phi)

Changed the name of the parameter

r2squaredsomething to normalize_dtheta_dphi for a better description
of what it does, also made the default no, so that by default
the components are normalised to the vector (dtheta, dphi), which seems
to be what people would expect.

This might mean rerunning some testsuites


git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/ADMAnalysis/trunk@5 80bd93c7-81bc-453a-9e3f-619c0b4f6fe4

5 files changed, 145 insertions, 28 deletions

diff --git a/README b/README
index 4d9f5eb..b325d61 100644
--- a/README
+++ b/README
@@ -24,8 +24,9 @@ if output is requested for them.
 
 (q refers to the theta coordinate and p to the phi coordinate.)
 
-If the parameter 'rsquared_in_sphm' is true, the thorn squares the
-radial coordinate when it uses it for the transformation.
+If the parameter 'normalize_dtheta_dphi' is true, the thorn 
+projects the spherical components onto (r*dtheta, r*sin(theta)*dphi)
+instead of the default vector (dtheta,dphi).
 
 This thorn knows how to handle 'physical' and 'static conformal'
 metric types.
diff --git a/doc/documentation.tex b/doc/documentation.tex
index e3730fc..4ac63f5 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -1,4 +1,26 @@
 \documentclass{article}
+
+\newif\ifpdf
+\ifx\pdfoutput\undefined
+\pdffalse % we are not running PDFLaTeX
+\else
+\pdfoutput=1 % we are running PDFLaTeX
+\pdftrue
+\fi
+
+\ifpdf
+\usepackage[pdftex]{graphicx}
+\else
+\usepackage{graphicx}
+\fi
+
+\parskip = 0 pt
+\parindent = 0pt
+\oddsidemargin = 0 cm
+\textwidth = 16 cm
+\topmargin = -1 cm
+\textheight = 24 cm
+
 \begin{document}
 
 \title{ADMAnalysis}
@@ -10,33 +32,126 @@
 
 \section{Purpose}
 
-This thorn calculates
+This thorn provides analysis routines to calculate the following quantities:
 
 \begin{itemize}
 \item
-The trace of the extrinsic curvature ({\bf trK}).
+The trace of the extrinsic curvature ($trK$).
 \item
-The determinant of the metric ({\bf detg}).
+The determinant of the 3-metric ($detg$).
 \item
-The components of the metric in spherical coordinates 
-({\bf grr,grq,grp,gqq,gqp,gpp}).
+The components of the 3-metric in spherical coordinates \\
+($g_{rr},g_{r\theta},g_{r\phi},g_{\theta\theta},g_{\phi\theta},g_{\phi\phi}$).
 \item
-The components of the extrinsic curvature in spherical coordinates 
-({\bf Krr,Krq,Krp,Kqq,Kqp,Kpp}).
+The components of the extrinsic curvature in spherical coordinates \\
+($K_{rr},K_{r\theta},K_{r\phi},K_{\theta\theta},K_{\theta\phi},K_{\phi\phi}$).
 \end{itemize}
 
-if output is requested for them.
+\section{Trace of Extrinsic Curvature}
+
+The trace of the extrinsic curvature at each point on the grid is placed in
+the grid function {\tt trK}. The algorithm for calculating the trace 
+uses the physical metric, that is it includes any conformal factor.
+
+\begin{equation}
+{\tt trK} \equiv tr K = \frac{1}{\psi^4} g^{ij} K_{ij}
+\end{equation}
 
-\section{Comments}
+\section{Determinant of 3-Metric}
 
-If the parameter {\bf rsquared\_in\_sphm} is set, it squares the
-radial coordinate before applying the tranformation.
+The determinant of the 3-metric at each point on the grid is placed in
+the grid function {\tt detg}. This is always the determinant of the 
+conformal metric, that is it does not include any conformal factor.
 
-In the spherical transormation, the $\theta$ coordinate is referred to
+\begin{equation}
+{\tt detg} \equiv det g =
+-g_{13}^2*g_{22}+2*g_{12}*g_{13}*g_{23}-g_{11}*g_{23}^2-
+g_{12}^2*g_{33}+g_{11}*g_{22}*g_{33}
+\end{equation}
+
+
+\section{Transformation to Spherical Cooordinates}
+
+The values of the metric and/or extrinsic curvature in a spherical
+polar coordinate system $(r,\theta,\phi)$ evaluated at each point on
+the computational grid are placed in the grid functions ({\tt grr},
+{\tt grt}, {\tt grp}, {\tt gtt}, {\tt gtp}, {\tt gpp}) and ({\tt krr},
+{\tt krt}, {\tt krp}, {\tt ktt}, {\tt ktp}, {\tt kpp}).
+In the spherical transformation, the $\theta$ coordinate is referred to
 as {\bf q} and the $\phi$ as {\bf p}.
 
-This thorn knows how to handle `physical' and `static conformal'
-metric types.
+The general transformation from Cartesian to Spherical for such tensors 
+is
+
+\begin{eqnarray*}
+A_{rr}&=&
+\sin^2\theta\cos^2\phi A_{xx}
++\sin^2\theta\sin^2\phi A_{yy}
++\cos^2\theta A_{zz}
++2\sin^2\theta\cos\phi\sin\phi A_{xy}
+\\
+&&
++2\sin\theta\cos\theta\cos\phi A_{xz}
++2\sin\theta\cos\theta\sin\phi A_{yz}
+\\
+A_{r\theta}&=&
+r(\sin\theta\cos\theta\cos^2\phi A_{xx}
++2*\sin\theta\cos\theta\sin\phi\cos\phi A_{xy}
++(\cos^2\theta-\sin^2\theta)\cos\phi A_{xz}
+\\
+&&
++\sin\theta\cos\theta\sin^2\phi A_{yy}
++(\cos^2\theta-\sin^2\theta)\sin\phi A_{yz}
+-\sin\theta\cos\theta A_{zz})
+\\
+A_{r\phi}&=&
+r\sin\theta(-\sin\theta\sin\phi\cos\phi A_{xx}
+-\sin\theta(\sin^2\phi-\cos^2\phi)A_{xy}
+-\cos\theta\sin\phi A_{xz}
+\\
+&&
++\sin\theta\sin\phi\cos\phi A_{yy}
++\cos\theta\cos\phi A_{yz})
+\\
+A_{\theta\theta}&=&
+r^2(\cos^2\theta\cos^2\phi A_{xx}
++2\cos^2\theta\sin\phi\cos\phi A_{xy}
+-2\sin\theta\cos\theta\cos\phi A_{xz}
++\cos^2\theta\sin^2\phi A_{yy}
+\\
+&&
+-2\sin\theta\cos\theta\sin\phi A_{yz}
++\sin^2\theta A_{zz})
+\\
+A_{\theta\phi}&=&
+r^2\sin\theta(-\cos\theta\sin\phi\cos\phi A_{xx}
+-\cos\theta(\sin^2\phi-\cos^2\phi)A_{xy}
++\sin\theta \sin\phi A_{xz}
+\\
+&&
++\cos\theta\sin\phi\cos\phi A_{yy}
+-\sin\theta\cos\phi A_{yz})
+\\
+A_{\phi\phi}&=&
+r^2\sin^2\theta(\sin^2\phi A_{xx}
+-2\sin\phi\cos\phi A_{xy}
++\cos^2\phi A_{yy})
+\end{eqnarray*}
+
+If the parameter {\tt normalize\_dtheta\_dphi} is set to {\tt yes}, 
+the angular components are projected onto the vectors $(r d\theta, r \sin\theta d \phi)$ instead of the default vector $(d \theta, d\phi)$. That is,
+
+\begin{eqnarray*}
+A_{\theta\theta} & \rightarrow & A_{\theta\theta}/r^2
+\\
+A_{\phi\phi}& \rightarrow & A_{\phi\phi}/(r^2\sin^2\theta)
+\\
+A_{r\theta} & \rightarrow & A_{r\theta}/r
+\\
+A_{r\phi} & \rightarrow & A_{r\phi}/(r\sin\theta)
+\\
+A_{\theta\phi} & \rightarrow & A_{\theta\phi}/r^2\sin\theta)
+\end{eqnarray*}
 
 % Automatically created from the ccl files by using gmake thorndoc
 \include{interface}
diff --git a/param.ccl b/param.ccl
index 3a9e0bd..69727c7 100644
--- a/param.ccl
+++ b/param.ccl
@@ -7,6 +7,6 @@ USES KEYWORD metric_type
 
 private:
 
-BOOLEAN rsquared_in_sphm "Use r^2 when calculating spherical components ?"
+BOOLEAN normalize_dtheta_dphi "Project angular components onto r*dtheta and r*sin(theta)*dphi?"
 {
 } "no"
diff --git a/src/Analysis.c b/src/Analysis.c
index c962ba4..d4ad471 100644
--- a/src/Analysis.c
+++ b/src/Analysis.c
@@ -119,7 +119,7 @@ void ADMAnalysis_MetricCartToSphere(CCTK_ARGUMENTS)
   DECLARE_CCTK_PARAMETERS;
 
   ADMAnalysis_CartToSphere(cctk_lsh,
-                           rsquared_in_sphm,
+                           normalize_dtheta_dphi,
                            x,
                            y,
                            z,
@@ -159,7 +159,7 @@ void ADMAnalysis_CurvCartToSphere(CCTK_ARGUMENTS)
   DECLARE_CCTK_PARAMETERS;
 
   ADMAnalysis_CartToSphere(cctk_lsh,
-                           rsquared_in_sphm,
+                           normalize_dtheta_dphi,
                            x,
                            y,
                            z,
diff --git a/src/CartToSphere.c b/src/CartToSphere.c
index 00d074a..e5e674f 100644
--- a/src/CartToSphere.c
+++ b/src/CartToSphere.c
@@ -64,8 +64,9 @@ CCTK_FILEVERSION(CactusEinstein_ADMAnalysis_CartToSphere_c)
    @vdesc   the local shape of the grid
    @vtype   const int *
    @vio     in
-   @var     r2norm
-   @vdesc   a flag which is set if the radius variable shouldbe squared
+   @var     project_rdtheta_rdphi
+   @vdesc   If set project angular components onto r*dtheta and 
+   r*sin(theta)*dphi instead of dtheta and dphi
    @vtype   int
    @vio     in
    @var     x
@@ -135,7 +136,7 @@ CCTK_FILEVERSION(CactusEinstein_ADMAnalysis_CartToSphere_c)
 
  @@*/
 void ADMAnalysis_CartToSphere(const CCTK_INT *lsh,
-                              int r2norm,
+                              int project_rdtheta_rdphi,
                               const CCTK_REAL *x,
                               const CCTK_REAL *y,
                               const CCTK_REAL *z,
@@ -215,7 +216,7 @@ void ADMAnalysis_CartToSphere(const CCTK_INT *lsh,
           2*cosp*SQR(cost)*txy*sinp
           +SQR(cosp)*SQR(cost)*txx);
      
-     if (r2norm) 
+     if (!project_rdtheta_rdphi) 
      {
        sphere_qq[i] *= SQR(r[i]);
      }
@@ -225,7 +226,7 @@ void ADMAnalysis_CartToSphere(const CCTK_INT *lsh,
           2*cosp*txy*sinp+
           SQR(cosp)*tyy);
      
-     if (r2norm)  
+     if (!project_rdtheta_rdphi)  
      {
        sphere_pp[i] *= SQR(r[i]) * SQR(sint);
      }
@@ -238,9 +239,9 @@ void ADMAnalysis_CartToSphere(const CCTK_INT *lsh,
           2*SQR(cost)*tyz*sinp-
           tyz*sinp+
           2*cosp*SQR(cost)*txz-
-          cosp*txz)*r[i];
+          cosp*txz);
      
-     if (r2norm) 
+     if (!project_rdtheta_rdphi) 
      {
        sphere_rq[i] *= r[i];
      }
@@ -251,7 +252,7 @@ void ADMAnalysis_CartToSphere(const CCTK_INT *lsh,
            SQR(cosp)*txy)*sint-
           cost*txz*sinp+cosp*cost*tyz);
      
-     if (r2norm)  
+     if (!project_rdtheta_rdphi)  
      {
        sphere_rp[i] *= r[i] * sint;
      }
@@ -261,7 +262,7 @@ void ADMAnalysis_CartToSphere(const CCTK_INT *lsh,
           cost*(-txy*SQR(sinp)+
                 cosp*(tyy-txx)*sinp+SQR(cosp)*txy));
 
-     if (r2norm) 
+     if (!project_rdtheta_rdphi) 
      {
        sphere_qp[i] *= SQR(r[i]) * sint;
      }