Added some details to the CalcTmunu section.

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinBase/ADMCoupling/trunk@8 a4c7b220-a359-4231-b37a-efab6cb7d3ee

1 files changed, 42 insertions, 15 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 663abcd..335a9d3 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -46,21 +46,43 @@ components of the stress energy tensor.  This is done using the Cactus
 include file mechanism, which allows thorns to contribute code to
 include files, which can then be included by any thorn which wishes to
 use them.
-
-For \texttt{CalcTmunu} there are two include files,
+For \texttt{CalcTmunu} there are two include files\footnote{There used
+to be a third, \texttt{CalcTmunu\_rfr.inc}, which was a Cactus 3 legacy
+having to do with the rfr scheduling mechanism.  You may safely delete
+any reference to this file.},
 \texttt{CalcTmunu.inc} and \texttt{CalcTmunu\_temps.inc}.  
 %The name ``temps'' is not so great, it would be better to have the
 %one ``source'' and the other ``declarations'', or something.
-In the former, one can place code of the form
+
+In \texttt{CalcTmunu.inc}, one can place code of the form
 \begin{verbatim}
 	Ttt = Ttt + ...
 	Ttx = Ttx + ...
-	...
+	Tty = Tty + ...
+	Ttz = Ttz + ...
+	Txx = Txx + ...
+	Txy = Txy + ...
+	Txz = Txz + ...
+	Tyy = Tyy + ...
+	Tyz = Tyz + ...
+	Tzz = Tzz + ...
 \end{verbatim}
-to add terms to the components $T_{\mu\nu}$.  This code will be
-executed for each point on the grid.  The latter will be
+to add terms to the components $T_{\mu\nu}$.  Each of these variables
+is of type \texttt{CCTK\_REAL}.  (If you omit the
+\texttt{Ttt \nolinebreak+}, \texttt{Ttx \nolinebreak+}, etc. from the right hand sides of
+these assignment statements then you will be assuming that your thorn
+is the only one which provides matter degrees of freedom, and
+excluding contributions from other matter thorns which may be
+activated.)
+This code will be
+executed for each point on the grid, whose indices will be stored in
+the integers \texttt{i}, \texttt{j}, and \texttt{k}.  Currently it must be 
+`fixed form' Fortran code.
+
+\texttt{CalcTmunu\_temps.inc} will be
 included in the variable declaration section for the block of code
 which contains the
+\nopagebreak
 \begin{verbatim}
 #include "CalcTmunu.inc"
 \end{verbatim}
@@ -71,19 +93,24 @@ declared within a macro from \texttt{ADMMacros}.
 \subsection{For matter thorns}
 To make use of the {\tt CalcTmunu} interface, simply place the lines
 \begin{verbatim}
-INCLUDES HEADER: MyThorn_CalcTmunu_temps.inc in CalcTmunu_temps.inc
-INCLUDES SOURCE: MyThorn_CalcTmunu.inc in CalcTmunu.inc
+INCLUDES HEADER: <MyThorn_CalcTmunu_temps.inc> in CalcTmunu_temps.inc
+INCLUDES SOURCE: <MyThorn_CalcTmunu.inc> in CalcTmunu.inc
 \end{verbatim}
 in your thorn's \texttt{interface.ccl} file, and declare your thorn to
 be friends with \texttt{ADMCoupling}.  Then provide the files
-\texttt{MyThorn\_CalcTmunu\_temps.inc} and
-\texttt{MyThorn\_CalcTmunu.inc} (or whatever you choose to name them)
-somewhere in your thorn's source code.
+\texttt{<MyThorn\_CalcTmunu\_temps.inc>} and
+\texttt{<MyThorn\_CalcTmunu.inc>} somewhere in your thorn's source
+code.
+We expect to add a sample matter thorn to \texttt{CactusEinstein}
+soon, which will illustrate the use of this.
 
 \subsection{For thorns which need the stress energy tensor}
-
-See thorn \texttt{CactusEinstein/ADM} for an example of a thorn which
-uses the code inserted into the \texttt{CalcTmunu} include files.
+Spacetime evolution thorns and various analysis thorns (e.g. one which
+computes the constraints) may need to
+know the value of the stress-energy tensor.
+See thorn \texttt{CactusEinstein/ADM} for an example the former.
+%of a thorn which
+%uses the code inserted into the \texttt{CalcTmunu} include files.
 There the macro \texttt{KSOURCES} (see \texttt{KSOURCES\_declare.h}
 and \texttt{KSOURCES\_guts.h}) is called from the various time
 integration source files \texttt{DoubleLeap.F},
@@ -98,4 +125,4 @@ $T_{\mu\nu}$ temporary variables are provided by including
 
 \end{document}
 % LocalWords:  ADMCoupling Hawke Whisky CalcTmunu ADMConstraints Ttt Ttx ccl
-% LocalWords:  ADMMacros MyThorn KSOURCES DoubleLeap IterativeCN
+% LocalWords:  ADMMacros MyThorn KSOURCES DoubleLeap IterativeCN rfr CCTK