minor changes and added ConfPhys functions

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinBase/StaticConformal/trunk@10 0cbbb82d-14ec-4423-a1fb-2ab18257ecaa

1 files changed, 78 insertions, 26 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 0f80e0d..69b36f8 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -12,8 +12,8 @@
 
 This thorn provides the variables defining a static conformal factor
 which is used to transform the physical metric.  If this thorn is
-active and the {\bf ADMBase::metric\_type} parameter is set to
-`static conformal' then the {\bf ADMBase::g...} variables are the
+active and the {\tt ADMBase::metric\_type} parameter is set to
+{\tt static conformal} then the {\tt ADMBase::g...} variables are the
 conformal values as opposed to the physical values.
 
 The transformation is
@@ -22,50 +22,102 @@ $$ g_{ij}^{\mbox{physical}} = \psi^4 g_{ij}^{\mbox{conformal}} $$
 
 The extrinsic curvature is not transformed.
 
-Memory is provided for the conformal factor {\bf psi}, its first
-derivatives {\bf psix}, {\bf psiy}, {\bf psiz}, and its second
-derivatives {\bf psixx}, {\bf psixy}, {\bf psixz}, {\bf psiyy}, {\bf
-psiyz}, and {\bf psizz} depending on the setting of the {\bf
+Memory is provided for the conformal factor {\tt psi}, its first
+derivatives {\tt psix}, {\tt psiy}, {\tt psiz}, and its second
+derivatives {\tt psixx}, {\tt psixy}, {\tt psixz}, {\tt psiyy}, {\tt
+psiyz}, and {\tt psizz} depending on the setting of the {\tt
 conformal\_storage} parameter.
 
 Note that the first and second ``derivative'' grid functions have an
 additional factor of $1 / \psi$ normalisation since this is the most
 common use of the derivative.  I.e. the grid functions are
 
-$$ \psi $$
-$$ \psi_i/\psi$$
-and
-
-$$ \psi_{ij}/\psi $$
+\begin{eqnarray*}
+ {\tt psi} &=& \psi, \\
+ {\tt psix} &=& \psi_x/\psi, \qquad {\mbox etc}\\
+ {\tt psixx} &=& \psi_{ij}/\psi \qquad {\mbox etc}
+\end{eqnarray*}
 
 Thorns need to check the value of the grid scalar 
-{\bf conformal\_state} to determine how many levels of these variables have
-actually been calculated.
+{\tt conformal\_state} to determine how many levels of these variables have
+actually been calculated before using the conformal factor:
 
-\begin{itemize}
-\item[0] 
+\begin{description}
+\item[{\tt conformal\_state=0}] 
 No conformal factor has been calculated -- thorns may
 assume the conformal factor is 1 at all points.  (I.e. the metric is physical.)
-\item[1] 
+\item[{\tt conformal\_state=1}] 
 The conformal factor has been calulated, but no derivatives.
-\item[2]
+\item[{\tt conformal\_state=2}]
 The conformal factor and its first derivatives have been calculated.
-\item[3]
+\item[{\tt conformal\_state=3}]
 The conformal factor and its first and second derivatives have been calculated.
-\end{itemize}
+\end{description}
+
+Note that this means that if you only want to know whether {\tt psi} contains 
+the values for the conformal factor you can check for {\tt conformal\_state > 0}.
+
+\section{Utilities}
+
+{\tt StaticConformal} provides functions to convert between physical and conformal 3-metric values. It is very important to understand that these functions 
+apply the conversion {\it in place}. That is, if {\tt gxx} contains the conformal metric value, when the routine is exited it will now contain the physical metric value. This functions {\it do not} change the value of {\tt conformal\_state} and should be used with due care. (These functions are for example used
+by some analysis thorns who work only with the physical metric, they apply the
+transformation on entry to the analysis routine and switch it back on exit).
+
+\begin{description}
+
+\item[Convert from conformal to physical:]
+
+{\tt
+\begin{verbatim}
+
+
+StaticConf_ConfToPhysInPlace (cctk_lsh(1),
+                              cctk_lsh(2),
+                              cctk_lsh(3),
+                              psi,
+                              gxx,
+                              gxy,
+                              gxz,
+                              gyy,
+                              gyz,
+                              gzz)
+\end{verbatim}
+}
+
+\item[Convert from physical to conformal:]
+
+{\tt
+\begin{verbatim}
+
+
+StaticConf_PhysToConfInPlace (cctk_lsh(1),
+                              cctk_lsh(2),
+                              cctk_lsh(3),
+                              psi,
+                              gxx,
+                              gxy,
+                              gxz,
+                              gyy,
+                              gyz,
+                              gzz)
+\end{verbatim}
+}
+
+\end{description}
 
 \section{Comments}
 
-The {\bf StaticConformal} thorn itself does not calculate any conformal
-factor, but does initialise the {\bf conformal\_state} variable to 0. 
+The {\tt StaticConformal} thorn itself does not calculate any conformal
+factor, but does initialise the {\tt conformal\_state} variable to 0. 
 
-Please note, no thorn should use the conformal\_state variable unless
-metric\_type is "static conformal".  The conformal\_state variable is
-not assigned storage or initialised by the StaticConformal thorn in
-any other case.
+Please note, no thorn should use the {\tt conformal\_state} variable
+unless the parameter {\tt metric\_type} is {\tt "static conformal"}.
+The {\tt conformal\_state} variable is not assigned storage or
+initialised by the StaticConformal thorn in any other case.
 
 However thorns are free to themselves assigned storage for
-conformal\_state and initialised it to zero if metric\_type is
+{\tt conformal\_state} and initialise it to zero if {\tt metric\_type} is
 "physical".  In this one case is it safe for them to use
 the conformal\_state variable if metric\_type is not "static
 conformal".  This method allows them to use just one set of ifs rather