diff options
Diffstat (limited to 'doc/documentation.tex')
| -rw-r--r-- | doc/documentation.tex | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/doc/documentation.tex b/doc/documentation.tex new file mode 100644 index 0000000..81f0934 --- /dev/null +++ b/doc/documentation.tex @@ -0,0 +1,358 @@ +% *======================================================================* +% 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} |