Cactus Code Thorn TimeGeodesic
Author(s)    : Miguel Alcubierre
               Florian Siebel
Maintainer(s): Cactus team
Licence      : LGPL
--------------------------------------------------------------------------

1. Purpose

This thorn integrates timelike geodesics.  The integration is
done `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:

num_active:  Integration of geodesics on
             numerical spacetime [yes,no].

num_test:    Tests of geodesic integration
             on numerical spacetime [yes,no].

num_IJ:      Calculate invariants I and J on
             numerical spacetime [yes,no].
             `Yes' option requires thorn: PsiKadelia.
             (This should probably be changed to Zorro?)
 
exa_active:  Integration of geodesics on
             exact spacetime [yes,no].
             `Yes' option requires thorn: Exact.

exa_IJ:      Calculate invariants I and J on
             exact spacetime [yes,no].

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 `ngeos'.

The initial positions of the geodesics are determined by
the values of the parameter `geopos':

   geopos = x00:  Uniform distribution along x axis.
   geopos = 0y0:  Uniform distribution along y axis.
   geopos = 00z:  Uniform distribution along z axis.

   geopos = xy0:  Uniform distribution along xy diagonal.
   geopos = x0z:  Uniform distribution along xz diagonal.
   geopos = 0yz:  Uniform distribution along yz diagonal.

   geopos = xyz:  Uniform distribution along xyz diagonal.

   geopos = grid: Uniform 3D down-sampled distribution.
                  The down sampling factor should be
                  given using the parameter `geo_sample'.

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

   geopos = file: Positions supplied by user from an
                  external file.

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:  (a = lapse, b = shift,
g = 3-metric, x = position, p = momentum)

        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
where p  is given by:

                                   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):

        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
with p  the same as before.


2. Dependencies of the thorn

For integration of geodesics in the numerical spacetime,
this thorn requires thorn PUGHInterp.

For integration of geodesics in the analytical spacetime,
this thorn requires thorn Exact.

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

For data streaming TimeGeodesic requires CactusNet/NetGeometry 
which requires external/RemoteIO and external/TCPXX.
Thorn ifdef's are used so that it can be compiled without
these, disabling the data streaming then. 

3. Thorn distribution

Everyone.

4. Additional information