path: root/doc/documentation.tex

% *======================================================================*
%  Cactus Thorn template for ThornGuide documentation
%  Author: Ian Kelley
%  Date: Sun Jun 02, 2002
%
%  Thorn documentation in the latex file doc/documentation.tex
%  will be included in ThornGuides built with the Cactus make system.
%  The scripts employed by the make system automatically include
%  pages about variables, parameters and scheduling parsed from the
%  relevant thorn CCL files.
%
%  This template contains guidelines which help to assure that your
%  documentation will be correctly added to ThornGuides. More
%  information is available in the Cactus UsersGuide.
%
%  Guidelines:
%   - Do not change anything before the line
%       % START CACTUS THORNGUIDE",
%     except for filling in the title, author, date, etc. fields.
%        - Each of these fields should only be on ONE line.
%        - Author names should be separated with a \\ or a comma.
%   - You can define your own macros, but they must appear after
%     the START CACTUS THORNGUIDE line, and must not redefine standard
%     latex commands.
%   - To avoid name clashes with other thorns, 'labels', 'citations',
%     'references', and 'image' names should conform to the following
%     convention:
%       ARRANGEMENT_THORN_LABEL
%     For example, an image wave.eps in the arrangement CactusWave and
%     thorn WaveToyC should be renamed to CactusWave_WaveToyC_wave.eps
%   - Graphics should only be included using the graphicx package.
%     More specifically, with the "\includegraphics" command.  Do
%     not specify any graphic file extensions in your .tex file. This
%     will allow us to create a PDF version of the ThornGuide
%     via pdflatex.
%   - References should be included with the latex "\bibitem" command.
%   - Use \begin{abstract}...\end{abstract} instead of \abstract{...}
%   - Do not use \appendix, instead include any appendices you need as
%     standard sections.
%   - For the benefit of our Perl scripts, and for future extensions,
%     please use simple latex.
%
% *======================================================================*
%
% Example of including a graphic image:
%    \begin{figure}[ht]
% 	\begin{center}
%    	   \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure}
% 	\end{center}
% 	\caption{Illustration of this and that}
% 	\label{MyArrangement_MyThorn_MyLabel}
%    \end{figure}
%
% Example of using a label:
%   \label{MyArrangement_MyThorn_MyLabel}
%
% Example of a citation:
%    \cite{MyArrangement_MyThorn_Author99}
%
% Example of including a reference
%   \bibitem{MyArrangement_MyThorn_Author99}
%   {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999),
%   1--16. {\tt http://www.nowhere.com/}}
%
% *======================================================================*

\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}

% The author of the documentation
\author{Erik Schnetter \textless schnetter@cct.lsu.edu\textgreater}

% The title of the document (not necessarily the name of the Thorn)
\title{QuasoLocalMeasures}

% the date your document was last changed
\date{2010-04-02}

\maketitle

% Do not delete next line
% START CACTUS THORNGUIDE

% Add all definitions used in this documentation here
%   \def\mydef etc

% Add an abstract for this thorn's documentation
\begin{abstract}
  Calculate quasi-local measures such as masses, momenta, or angular
  momenta and related quantities on closed two-dimentional surfaces,
  including on horizons.
\end{abstract}

% The following sections are suggestive only.
% Remove them or add your own.

\section{A note on evaluating 3D integrals on the horizon world tube}

[NOTE: Ignore the stuff below.  You can do that much easier.]

\subsection{Integral transformation}

The papers about dynamical horizons contain integrals over the 3D
horizon world tube, expressed e.g.\ as
\begin{eqnarray}
   \int X\; d^3V
\end{eqnarray}
where $X$ is some quantity that lives on the horizon.  These integrals
have to be transformed into a $2+1$ form so that they can be
conveniently evaluated, e.g.\ as
\begin{eqnarray}
   \int X\; A\, d^2S\, dt
\end{eqnarray}
where $d^2S$ is the area element on the horizon cross section
contained in $\Sigma$, and $dt$ is the coordinate time differential.
The factor $A$ should contain the extra terms due to this coordinate
transformation.

Starting from the $3$-volume element $d^3V$, let us first decompose
it into the $2$-volume element $d^2S$ and a ``time'' coordinate on the
horizon, which we call $\sigma$.  Note that $\sigma$ will generally be
a spacelike coordinate for dynamical horizons.  Let $\mathbf{Q}$ be
the induced $3$-metric on the horizon, and $\mathbf{q}$ be the induced
$2$-metric on the cross section.
Then it is
\begin{eqnarray}
   d^3V & = & \sqrt{\det Q}\; d\theta\, d\phi\, d\sigma
\\
   & = & \frac{\sqrt{\det Q}}{\sqrt{\det q}}\; d^2S\, d\sigma
\end{eqnarray}
because $d^2S = \sqrt{\det q}\, d\theta\, d\phi$.

The coordinate time differential $dt$ and the differential $d\sigma$
will in general not be aligned because the horizon world tube will in
general not have a static coordinate shape.  It is
\begin{eqnarray}
   d\tau   & = & (\cosh \alpha)\, dt + (\sinh \alpha)\, ds
\\
   d\sigma & = & (\cosh \alpha)\, ds + (\sinh \alpha)\, dt
\end{eqnarray}
where $s$ is a radial coordinate perpendicular to the horizon and also
perpendicular to $t$, and $\tau$ is perpendicular to $\sigma$ and lies
in the plan spanned by $t$ and $s$.  $\tau$ and $\sigma$ are depend on
$t$ and $s$ via a Lorentz boost.  Thus we have
\begin{eqnarray}
   \frac{d\sigma}{dt} & = & (\cosh \alpha)\, \frac{ds}{dt} + (\sinh
   \alpha)\, \frac{dt}{dt}
\\
   & = & \sinh \alpha \quad\textrm{.}
\end{eqnarray}

Putting everything together we arrive at
\begin{eqnarray}
   \int X\; \frac{\sqrt{\det Q}}{\sqrt{\det q}}\; (\sinh \alpha)\,
   d^2S\, dt \quad\textrm{.}
\end{eqnarray}



\subsection{The ``lapse'' function $N_R$}

Starting from
\begin{eqnarray}
   N_R & = & | \partial R |
\end{eqnarray}
we find, since the radius $R$ changes only in the $\sigma$ direction,
\begin{eqnarray}
   N_R^2 & = & g^{\sigma\sigma}\, (\partial_\sigma R)\,
   (\partial_\sigma R) \quad\textrm{.}
\end{eqnarray}

If we assume $\partial_\tau R = 0$ and write $\partial_t R = \dot R$,
and use the relations between $\sigma$ and $t$ from above, we get
\begin{eqnarray}
   \dot R & = & \partial_t R
\\
   & = & \frac{\partial \tau}{\partial t} \partial_\tau R +
   \frac{\partial \sigma}{\partial t} \partial_\sigma R
\\
   & = & \sinh \alpha\, \partial_\sigma R
\end{eqnarray}
[NOTE: but $\partial_t \alpha \ne 0$.]
and therefore
\begin{eqnarray}
   \partial_\sigma R & = & \frac{1}{\sinh \alpha}\; \dot R
   \quad\textrm{.}
\end{eqnarray}

Additionally we have $g^{\sigma\sigma} = g^{ab} \sigma_a \sigma_b =
g_{ab} \sigma^a \sigma^b$ where $\sigma^a$ is the unit vector in the
$\sigma$ direction, i.e.\
\begin{eqnarray}
   \tau^a   & = & (\cosh \alpha)\, t^a + (\sinh \alpha)\, s^a
\\
   \sigma^a & = & (\cosh \alpha)\, s^a + (\sinh \alpha)\, t^a
\end{eqnarray}



\subsection{Special Behaviour}

In order to use the IsolatedHorizon thorn on existing data
(postprocessing), the following procedure is necessary.

\begin{itemize}

\item

\begin{itemize}

Computing time-independent quantities.\\

The 3-metric and the extrinsic curvature must be available in HDF5
files.

\item Set up a parameter file for a grid structure that contains the
  region around the horizon.  The refinement level structure and grid
  spacing etc. needs to be the same as in the HDF5 files, but the
  grids can be much smaller.  You can also leave out some finer grids,
  i.e., reduce the number of levels.  However, the coarse grid spacing
  must remain the same.  The symmetries must also be the same.

\item Use the file reader and thorn AEIThorns/IDFileADM to read in the
  ADM variables from the files.  The parameter file does not need to
  activate BSSN\_MoL or any time evolution mechanism.  IDFileADM acts
  as provider for initial data, so you don't need any other initial
  data either.

\item Set up your parameter file so that the AH finder runs, stores
  the horizon shape in SphericalSurface,
  and IsolatedHorizon accesses these data.\\

\end{itemize}

This gives you the time-independent variables on the horizon, i.e.,
mostly the spin.  It also allows you to look for apparent horizons if
you don't know where they are.


\item
  Computing time-independent quantities, e.g.\ 3-determinant of the horizon\\

\begin{itemize}

\item Performing some time steps is necessary. Either read in lapse
  and shift from files, or set them arbitrarily (e.g.\ lapse one,
  shift zero).

\item Activate a time evolution thorn, i.e., BSSN\_MoL, MoL, Time,
  etc.  In order to fill the past time levels, just choose
  MoL::initial\_data\_is\_crap.  If you have hydrodynamics, read in
  the hydro variables as well.

\item Only two time steps are required. Remember that the output of
  IsolatedHorizon for iteration 0 and 1 are incorrect or very
  inaccurate, since the past time levels are not correct, and hence
  the time derivatives that IsolatedHorizon calculates are wrong.
  However, iteration 2 should be good.  (One could also perform 5
  iterations and cross-check.)

\end{itemize}


\item

  If data for the extrinsic curvature is not available, but those for
  the 3-metric, lapse, and shift for consecutive time steps are (that
  is, if you have data suitable for finding event horizons), then one
  needs to reconstruct the extrinsic curvature first.  There is a
  thorn AEIThorns/CalcK that helps with that.  It reads the data for
  the 4-metric timestep after timestep, calculates the time derivative
  of the 3-metric through finite differencing in time, and then
  determines the extrinsic curvature from that, and writes it to a
  file.  Once you have it, you can go on as above.  CalcK has a small
  shell script that tells you what to do.


\item

  In general, things become more interesting if a static conformal
  factor is involved (since more variables are present), especially if
  it is output only once (since it is static), which means that one
  has to mix variables from different time steps.

\end{itemize}

The thorns involved in this procedure have some examples.  In general,
this is NOT a ``just do it'' action; you have to know what you are
doing, since you have to put the pieces together in your parameter
file and make sure that everything is consistent.  We may have a
vision that you just call a script in a directory that contains output
files and the script figures out everything else, but we're not there
yet.  All the ingredients are there, but you'll have to put them
together in the right way.  Think Lego.



\section{Interpreting 2D output}

2D output is given on a rectangular grid.  This grid has coordinates
which are regular and have a constant spacing in the $\theta$ and
$\phi$ directions.  Cactus output has only grid point indices, but
does not contain the coordinates $\theta$ and $\phi$ themselves.

In gnuplot, one can define functions to convert indices to
coordinates:
\begin{eqnarray}
  \theta(i) & = & (i - g\theta + 0.5) * \pi   / n\theta
  \\
  \phi(j)   & = & (j - g\phi        ) * 2*\pi / n\phi
\end{eqnarray}
where $g\theta$ and $g\phi$ is the number of ghost points in the
corresponding direction, and $n\theta$ and $n\phi$ the number of
interior points.  Here are the same equations in gnuplot syntax:
\begin{verbatim}
theta(i) = (i - nghosts + 0.5) * pi / ntheta
phi(j) = (j - nghosts) * 2*pi / nphi
\end{verbatim}

Usually, \verb|nghosts=2|, \verb|ntheta=35|, and \verb|nphi=72|.
\verb|i| and \verb|j| are is the integer grid point indices.  Note
that \verb|ntheta| and \verb|nphi| in the parameter file include ghost
zones, while their definitions here do not include them.  In general,
\verb|nphi| is even and \verb|ntheta| is odd, because the points are
staggered about the poles.

A test plot shows whether the plot is symmetric about $\pi/2$ in the
$\theta$ and $\pi$ in the $\phi$ direction.  Also, plotting something
axisymmetric with bitant symmetry vs.\ $\theta$ and vs.\ $\pi-\theta$,
and vs.\ $\phi$ and $2\pi-\phi$, should lie exactly on top of each
other.

There are also scalars \verb|origin/delta_theta/phi| which one can use
in the above equations.  Then the equations read
\begin{verbatim}
theta(i) = (i + origin_theta) * delta_theta
phi(j) = (j + origin_phi) * delta_phi
\end{verbatim}
but, of course, these four quantities are all irrational and don't
look nice.



\begin{thebibliography}{9}

\end{thebibliography}

% Do not delete next line
% END CACTUS THORNGUIDE

\end{document}