Say roughly what is in each output file

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/Extract/trunk@66 5301f0c2-dbc4-4cee-b2f5-8d7afba4d129

1 files changed, 120 insertions, 61 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index c6b5738..61a932c 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -117,9 +117,15 @@
 
 \section{Introduction}
 
-Thorn Extract calculates first order gauge invariant waveforms from a numerical spacetime, under the basic assumption that, at the spheres of extract the spacetime is approximately Schwarzschild. In addition, other quantities such as mass, angular momentum and spin can be determined.
+Thorn Extract calculates first order gauge invariant waveforms from a
+numerical spacetime, under the basic assumption that, at the spheres
+of extract the spacetime is approximately Schwarzschild. In addition,
+other quantities such as mass, angular momentum and spin can be
+determined.
 
-This thorn should not be used blindly, it will always return some waveform, however it is up to the user to determine whether this is the appropriate expected first order gauge invariant waveform.
+This thorn should not be used blindly, it will always return some
+waveform, however it is up to the user to determine whether this is
+the appropriate expected first order gauge invariant waveform.
 
 \section{Physical System}
 
@@ -127,11 +133,13 @@ This thorn should not be used blindly, it will always return some waveform, howe
 
 Assume a spacetime $g_{\alpha\beta}$ which can be written as a Schwarzschild 
 background $g_{\alpha\beta}^{Schwarz}$ with perturbations $h_{\alpha\beta}$:
+%
 \begin{equation}
 g_{\alpha\beta} = g^{Schwarz}_{\alpha\beta} + h_{\alpha\beta}
 \end{equation}
 with
-$$
+%
+\begin{equation}
 \{g^{Schwarz}_{\alpha\beta}\}(t,r,\theta,\phi) = 
 \left( \begin{array}{cccc}
  -S & 0      & 0   & 0                \\
@@ -141,7 +149,7 @@ $$
 \end{array}\right)
 \qquad
 S(r)=1-\frac{2M}{r}
-$$
+\end{equation}
 %
 The 3-metric perturbations $\gamma_{ij}$ can be decomposed using tensor
 harmonics into  $\gamma_{ij}^{lm}(t,r)$ where
@@ -163,14 +171,11 @@ in 3-D Euclidean space.
 Working with the Regge-Wheeler basis (see Section~\ref{reggewheeler})
 the 3-metric is then expanded in terms of the (six) standard
 Regge-Wheeler functions $\{c_1^{\times lm}, c_2^{\times lm},
-h_1^{+lm}, H_2^{+lm}, K^{+lm}, G^{+lm}\}$
-\cite{regge},
-\cite{moncrief74}. 
-Where each of the functions is either  {\it odd} 
-  ($\times$) or 
-  {\it even} 
-  ($+$) 
-parity. The decomposition is then written 
+h_1^{+lm}, H_2^{+lm}, K^{+lm},
+G^{+lm}\}$~\cite{regge},~\cite{moncrief74}. Where each of the
+functions is either {\it odd} ($\times$) or {\it even} ($+$)
+parity. The decomposition is then written
+%
 \begin{eqnarray}
 \gamma_{ij}^{lm} & = & c_1^{\times lm}(\hat{e}_1)_{ij}^{lm}
                    +   c_2^{\times lm}(\hat{e}_2)_{ij}^{lm} 
@@ -180,7 +185,9 @@ parity. The decomposition is then written
                    +   R^2 K^{+lm}(\hat{f}_3)_{ij}^{lm}
                    +   R^2 G^{+lm}(\hat{f}_4)_{ij}^{lm}
 \end{eqnarray}
+%
 which we can write in an expanded form as 
+%
 \begin{eqnarray}
 \gamma_{rr}^{lm} 
   & = & A^2 H_2^{+lm} \Y 
@@ -206,31 +213,27 @@ which we can write in an expanded form as
         +R^2 K^{+lm}\sin^2\t \Y
         +R^2 G^{+lm} (\Ypp+\s\c \Yt)
 \end{eqnarray}
-
-A similar decomposition allows the four gauge components of the 4-metric to 
-be written in terms of  {\it three} even-parity variables 
-  $\{H_0,H_1,h_0\}$
-and the {\it one} odd-parity variable 
-  $\{c_0\}$ 
+%
+A similar decomposition allows the four gauge components of the
+4-metric to be written in terms of {\it three} even-parity variables
+$\{H_0,H_1,h_0\}$ and the {\it one} odd-parity variable $\{c_0\}$
+%
 \begin{eqnarray}
-g_{tt}^{lm} 
-  & = & N^2 H_0^{+lm} \Y 
+  g_{tt}^{lm} & = & N^2 H_0^{+lm} \Y 
 \\
-g_{tr}^{lm}
-  & = & H_1^{+lm} \Y
+  g_{tr}^{lm} & = & H_1^{+lm} \Y
 \\
-g_{t\t}^{lm}
-  & = & h_0^{+lm} \Yt - c_0^{\times lm}\frac{1}{\s}\Yp
+  g_{t\t}^{lm} & = & h_0^{+lm} \Yt - c_0^{\times lm}\frac{1}{\s}\Yp
 \\
-g_{t\p}^{lm}
-  & = & h_0^{+lm} \Yp + c_0^{\times lm} \s \Yt
-\end{eqnarray}         
+  g_{t\p}^{lm} & = & h_0^{+lm} \Yp + c_0^{\times lm} \s \Yt
+\end{eqnarray} 
+%        
 Also from $g_{tt}=-\alpha^2+\beta_i\beta^i$ we have
-$$
+%
+\begin{equation}
   \alpha^{lm} = -\frac{1}{2}NH_0^{+lm}Y_{lm}
-$$
-
-
+\end{equation}
+%
 It is useful to also write this with the perturbation split into even and
 odd parity parts:
 $$
@@ -338,59 +341,69 @@ where
 
 \section{Numerical Implementation}
 
-The implementation assumes that the numerical solution, on a Cartesian grid, 
-is approximately Schwarzshild on the spheres of constant $r=\sqrt(x^2+y^2+z^2)$
-where the waveforms are extracted. The general procedure is then:
+The implementation assumes that the numerical solution, on a Cartesian
+grid, is approximately Schwarzshild on the spheres of constant
+$r=\sqrt(x^2+y^2+z^2)$ where the waveforms are extracted. The general
+procedure is then:
 
 \begin{itemize}
 
-\item Project the required metric components, and radial derivatives of
-	metric components,
-      onto spheres of constant coordinate radius
-      (these spheres are chosen via parameters). 
+  \item Project the required metric components, and radial derivatives
+  of metric components, onto spheres of constant coordinate radius
+  (these spheres are chosen via parameters).
 
-\item Transform the metric components and there derivatives on the 2-spheres 
-	from Cartesian coordinates 
-	into a spherical coordinate system.
+  \item Transform the metric components and there derivatives on the
+  2-spheres from Cartesian coordinates into a spherical coordinate
+  system.
 
-\item Calculate the physical metric on these spheres if a conformal factor 
-	is being used.
+  \item Calculate the physical metric on these spheres if a conformal
+  factor is being used.
 
-\item Calculate the transformation from the coordinate radius to an areal radius for each 
-	sphere.
+  \item Calculate the transformation from the coordinate radius to an
+  areal radius for each sphere.
 
-\item Calculate the $S$ factor on each sphere. Combined with the areal radius This also produces an estimate of the mass.
+  \item Calculate the $S$ factor on each sphere. Combined with the
+  areal radius This also produces an estimate of the mass.
 
-\item Calculate the six Regge-Wheeler variables, and required radial derivatives, on these spheres by integration
-	of combinations of the metric components over each sphere. 
+  \item Calculate the six Regge-Wheeler variables, and required radial
+  derivatives, on these spheres by integration of combinations of the
+  metric components over each sphere.
 
-\item Contruct the gauge invariant quantities from these Regge-Wheeler variables.
+  \item Contruct the gauge invariant quantities from these
+  Regge-Wheeler variables.
 
 \end{itemize}
 
 \subsection{Project onto Spheres of Constant Radius}
 
-This is performed by interpolating the metric components, and if needed the conformal factor, onto the spheres. Although 2-spheres are hardcoded, the source code could easily be changed here to project onto e.g. 2-ellipsoids.
+This is performed by interpolating the metric components, and if
+needed the conformal factor, onto the spheres. Although 2-spheres are
+hardcoded, the source code could easily be changed here to project
+onto e.g. 2-ellipsoids.
 
 \subsection{Calculate Radial Transformation}
 
 The areal coordinate $\hat{r}$ of each sphere is calculated by
+%
 \begin{equation}
   \hat{r}    =  \hat{r}(r) = \left[
             \frac{1}{4\pi}
             \int\sqrt{\gamma_{\t\t}
             \gamma_{\p\p}}d\t d\p \right]^{1/2}
 \end{equation}
+%
 from which
+%
 \begin{equation}
 \frac{d\hat{r}}{d\eta} = \frac{1}{16\pi \hat{r}}
   \int\frac{\gamma_{\t\t,\eta}\gamma_{\p\p}+\gamma_{\t\t}\gamma_{\p\p,\eta}}
   {\sqrt{\gamma_{\t\t}\gamma_{\p\p}}} \ d\t d\p
 \end{equation}
-
+%
 Note that this is not the only way to combine metric components to get
-the areal radius, but this one was used because it gave better values 
-for extracting close to the event horizon for perturbations of black holes.
+the areal radius, but this one was used because it gave better values
+for extracting close to the event horizon for perturbations of black
+holes.
 
 \subsection{Calculate $S$ factor and Mass Estimate}
 
@@ -496,21 +509,67 @@ Use this thorn very carefully. Check the validity of the waveforms by running
 tests with different resolutions, different outer boundary conditions, etc
 to check that the waveforms are consistent.
 
-\subsection{Obtaining This Thorn}
+\subsection{Basic Usage}
 
-This thorn is part of the CactusEinstein arrangement.
+\subsection{Output Files}
 
-\subsection{Basic Usage}
+Although Extract is really an {\tt ANALYSIS} thorn, at the moment it
+is scheduled at {\tt POSTSTEP}, with the iterations at which output is
+performed determined by the parameter {\it itout}. Output files from
+{\tt Extract} are always placed in the main output directory defined
+by {\tt CactusBase/IOUtil}.
 
-\subsection{Special Behaviour}
+Output files are generated for each detector (2-sphere) used, and
+these detectors are identified in the name of each output file by {\tt
+R1}, {\tt R2}, \ldots.
 
-\subsection{Interaction With Other Thorns}
+The extension denotes whether coordinate time ({\.tl}) or proper time
+({\.ul}) is used for the first column.
 
-\section{History}
+\begin{itemize}
+
+  \item {\tt rsch\_R?.[tu]l} 
+
+	The extracted areal radius on each 2-sphere.
+
+  \item {\tt mass\_R?.[tu]l}
+
+	Mass estimate calculated from $g_{rr}$ on each 2-sphere.
+
+  \item {\tt Qeven\_R?\_??.[tu]l}
+
+	The even parity gauge invariate variable ({\it waveform}) on 
+	each 2-sphere. This is a complex quantity, the 2nd column is 
+	the real part, and the third column the imaginary part.
+
+  \item {\tt Qodd\_R?\_??.[tu]l}
 
-\subsection{Thorn Source Code}
+	The odd parity gauge invariate variable ({\it waveform}) on 
+	each 2-sphere. This is a complex quantity, the 2nd column is 
+	the real part, and the third column the imaginary part.
+
+  \item {\tt ADMmass\_R?.[tu]l}
+
+	Estimate of ADM mass enclosed within each 2-sphere.
+	(To produce this set {\tt doADMmass = ``yes''}).
+
+  \item {\tt momentum\_[xyz]\_R?.[tu]l}
+
+	Estimate of momentum at each 2-sphere.
+	(To produce this set {\tt do\_momentum = ``yes''}).
+
+  \item {\tt spin\_[xyz]\_R?.[tu]l}
+
+	Estimate of momentum at each 2-sphere.
+	(To produce this set {\tt do\_spin = ``yes''}).
+
+
+\end{itemize}
+
+\section{History}
 
-Much of the source code for Extract comes from a code written outside
+Much of the source code
+ for Extract comes from a code written outside
 of Cactus for extracting waveforms from data generated by the NCSA
 G-Code for compare with linear evolutions of waveforms extracted from
 the Cauchy initial data.  This work was carried out in collaboration