\documentclass{article}

% Use the Cactus ThornGuide style file
% (Automatically used from Cactus distribution, if you have a 
%  thorn without the Cactus Flesh download this from the Cactus
%  homepage at www.cactuscode.org)
\usepackage{../../../../doc/latex/cactus}

\begin{document}

\title{Cactus Code Thorn {\tt TimeGeodesic}}
\author{Miguel Alcubierre (building on work done by Florian Siebel)}
\date{$ $Date$ $}

\maketitle

% Do not delete next line
% START CACTUS THORNGUIDE

\begin{abstract}
This thorn integrates timelike geodesics.
\end{abstract}

\section{Purpose of the thorn}

This thorn integrates timelike geodesics.  The integration is
done {\it on the fly}, that is, at the same time as the evolution
of the spacetime is being calculated.  The thorn can calculate
geodesics either on the numerical spacetime, or on an exact
spacetime (given by thorn Exact).\\

The thorn is activated by the following parameters:\\

\begin{tabular}{ll}
{\tt num\_active:} & Integration of geodesics on
             numerical spacetime [yes,no].\\

{\tt num\_test:}   & Tests of geodesic integration
             on numerical spacetime [yes,no].\\

{\tt num\_IJ:}     & Calculate invariants $I$ and $J$ on
             numerical spacetime [yes,no].\\
		   & {\tt Yes} option requires thorn: PsiKadelia.
	             (This should probably be changed to Zorro?)\\
 
{\tt exa\_active:} & Integration of geodesics on
             exact spacetime [yes,no].
             {\tt Yes} option requires thorn: Exact.\\

{\tt exa\_IJ:}     & Calculate invariants I and J on
             exact spacetime [yes,no].\\
\end{tabular}\\

The fundamental variables used are the position of the geodesics
and the covariant components of the momentum.  The reason for
using the covariant components of the momentum as fundamental
variables instead of the more natural contravariant components
is that the geodesic equations become in fact much simpler this
way, and all time derivatives of the metric drop out.\\

The initial number of geodesics is determined by the value
of the parameter {\tt ngeos}.\\

The initial positions of the geodesics are determined by
the values of the parameter {\tt geopos}:\\


\begin{tabular}{ll}
   {\tt geopos = x00:} &  Uniform distribution along x axis.\\
   {\tt geopos = 0y0:} &  Uniform distribution along y axis.\\
   {\tt geopos = 00z:} &  Uniform distribution along z axis.\\

   {\tt geopos = xy0:} &  Uniform distribution along xy diagonal.\\
   {\tt geopos = x0z:} &  Uniform distribution along xz diagonal.\\
   {\tt geopos = 0yz:} &  Uniform distribution along yz diagonal.\\

   {\tt geopos = xyz:} &  Uniform distribution along xyz diagonal.\\

   {\tt geopos = grid:} & Uniform 3D down-sampled distribution.\\
&                  The down sampling factor should be
                  given using the parameter {\tt geo\_sample}.\\
\end{tabular}\\


The following option is there, but is not implemented yet:\\

\begin{tabular}{ll}
   geopos = file: Positions supplied by user from an
                  external file.
\end{tabular}\\

I also choose the initial geodesics to point in the
normal direction to the hypersurfaces.  This can be easily
changed if someone really needs it.\\

For the numerical spacetime, I use coordinate time as the
parameter, and I integrate proper time along the geodesics.
The form of the equations used is:  ($\alpha$~=~{\tt lapse}, 
$\beta$~=~{\tt shift}, $\gamma$~=~{\tt 3-metric}, $x$~=~{\tt position}, 
$p$~=~{\tt momentum})

\begin{eqnarray}
\frac{dx^i}{dt} &=& - \beta^i + \gamma^{ik}\frac{p_k}{p^0}\\\nonumber
\frac{dp_i}{dt} &=& -\alpha p^0 \frac{\partial \alpha}{\partial x^i} +
                     p_k \frac{\partial b^k}{\partial x^i} -
                     \frac{p_k p_j}{2 p^0}\frac{\partial 
                     \gamma^{kj}}{\partial x^i}\\\nonumber
\frac{d\tau}{dt} &=& \frac{1}{p^0}
\end{eqnarray}


%        i              i      ik       0
%     d x / dt    =  - b   +  g   p  / p
%                                  k
%
%                         0               k               kj      0
%     d p / dt    =  - a p  d a  +  p  d b   -  p  p  d  g   / 2 p
%        i                   i       k  i        k  j  i
%
%                         0
%     d tau / dt  =  1 / p
%

%       0
\noindent where $p$  is given by:

\begin{equation}
p^0 = \frac{1}{\alpha} \sqrt{1 + \gamma^{kj} p_k p_j}
\end{equation}

%                                   1/2
%      0      1  /        kj       \
%     p   =   -  | 1  +  g   p  p  |
%             a  \            k  j /


For the exact spacetime, I use proper time as the
parameter.  This is because I don't know which exact
coordinate time corresponds to a given numerical coordinate
time (the solutions might be on different gauges).
The form of the equations is then slightly different from
those given above (there is an extra factor P0):

\begin{eqnarray}
\frac{dx^i}{d\tau} &=& - \beta^i p^0 + \gamma^{ik}p_k\\\nonumber
\frac{dp_i}{d\tau} &=& -\alpha (p^0)^2 \frac{\partial \alpha}{\partial x^i}
                       + p^0 p_k \frac{\partial \beta^k}{\partial x^i}
                       - \frac{1}{2}p_k p_j \frac{\partial g^{kj}}{\partial x^i}
\end{eqnarray}


%        i               i  0      ik
%     d x / d tau  =  - b  p   +  g   p
%                                   k

%                           0 2          0       k               kj
%     d p / d tau  =  - a (p )  d a  +  p  p  d b   -  p  p  d  g   / 2
%        i                       i          k  i        k  j  i

%      0

\noindent with $p^0$ the same as before.\\


\section{Dependencies of the thorn}

For integration of geodesics in the numerical spacetime,
this thorn requires thorn {\tt PUGHInterp}.\\

For integration of geodesics in the analytical spacetime,
this thorn requires thorn {\tt Exact}.\\

For calculating the curvature invariants I and J in the
numerical spacetime this thorn additionally requires
thorn {\tt PsiKadelia}. (Zorro?).\\

For data streaming {\tt TimeGeodesic} requires {\tt CactusNet/NetGeometry} 
which requires {\tt external/RemoteIO} and {\tt external/TCPXX} which 
I've not been able to re-plug this time ({\bf [Francisco, 08.05.2002]}).
Thorn ifdef's are used so that it can be compiled without
these, disabling the data streaming. 

\section{Thorn distribution}

Everyone.

\section{Additional information}

% Do not delete next line
% END CACTUS THORNGUIDE

\end{document}
