% *======================================================================* % 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}