diff options
| -rw-r--r-- | doc/README | 4 | ||||
| -rw-r--r-- | doc/TODO | 2 | ||||
| -rw-r--r-- | doc/ahfinderdirect.bib | 13 | ||||
| -rw-r--r-- | doc/documentation.tex | 689 |
4 files changed, 570 insertions, 138 deletions
@@ -1 +1,5 @@ This directory holds documentation for the AHFinderDirect thorn. + +The makefile can automate running latex/bibtex: just type + make; make; make bib; make; make +and you should have dvi and postscript files. @@ -5,7 +5,7 @@ small things medium things there should be a Cactus test suite HDF5 data files - move origin point + move origin point to track moving BHs export a "compute h(theta,phi)" function so other thorns could test point membership in/outside AH etc prevent h from going negative if the iteration isn't converging diff --git a/doc/ahfinderdirect.bib b/doc/ahfinderdirect.bib index cd5e497..6be9270 100644 --- a/doc/ahfinderdirect.bib +++ b/doc/ahfinderdirect.bib @@ -50,6 +50,19 @@ year = "2002", eprint = "gr-qc/0206008" } +@article +{ +AEIDevelopment_AHFinderDirect_Gundlach-1998-apparent-horizon-finding, +author = "Carsten Gundlach", +title = "Pseudo-spectral apparent horizon finders: an efficient new algorithm", +journal = "Physical Review~D", +volume = 57, X-number = "FIXME", +year = 1998, month = "FIXME", +pages = "863--875", +eprint = "gr-qc/9707050", + +} + @techreport { AEIDevelopment_AHFinderDirect_Huq-Choptuik-Matzner-2000-3D-xyz-apparent-horizon-finding, diff --git a/doc/documentation.tex b/doc/documentation.tex index 94c56cd..c2a888f 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -138,8 +138,8 @@ The \thorn{AHFinderDirect} thorn locates apparent horizons in a numerically computed slice using a direct method, posing the apparent horizon equation as an elliptic PDE on angular-coordinate space. This -is very fast, but requires a ``reasonable'' initial guess. This -thorn guide describes how to use the thorn. +is very fast and accurate, but requires a ``reasonable'' initial guess. +This thorn guide describes how to use the thorn. \end{abstract} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -163,13 +163,9 @@ derivation of~\eqref{AEIDevelopment_AHFinderDirect_eqn-horizon}.) Thorn~\thorn{AHFinderDirect} finds an apparent horizon by numerically solving~\eqref{AEIDevelopment_AHFinderDirect_eqn-horizon}. It requires as input the usual Cactus 3-metric $g_\ij$ and extrinsic curvature -$K_\ij$,%%% -\footnote{%%% - And the conformal factor $\psi$ if the - \thorn{StaticConformal} metric semantics - are used. - }%%% -{} and produces as output the Cactus $(x,y,z)$ coordinates of a large +$K_\ij$, (and optionally the conformal factor $\psi$ if the +\thorn{StaticConformal} metric semantics are used), +and produces as output the Cactus $(x,y,z)$ coordinates of a large number of points on the apparent horizon, together with some auxiliary information like the apparent horizon area and centroid position, and the irreducable mass associated with the area. @@ -177,13 +173,14 @@ the irreducable mass associated with the area. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{How \thorn{AHFinderDirect} Works} +\label{AEIDevelopment_AHFinderDirect_sect-how-ahfinderdirect-works} The apparent horizon (henceforth \defn{horizon}) finding algorithm used in this thorn is basically that of \cite{AEIDevelopment_AHFinderDirect_Thornburg-1996-apparent-horizon-finding}, but modified to work with $g_\ij$ and $K_\ij$ on a Cartesian ($xyz$) grid: -We assume that a local coordinate origin has been chosen such that +I assume that a local coordinate origin has been chosen such that relative to that origin, the horizon is a \defn{Strahlk\"{o}rper} (``ray body''), defined by Minkowski (\cite[p.~108]{AEIDevelopment_AHFinderDirect_Schroeder-1986-number-theory}) @@ -193,18 +190,18 @@ as origin and whose surface, as seen from the origin, exhibits only one point in any direction. \end{quote} -We can thus parameterize the horizon's shape by $r = h({\rm angle})$ +I can thus parameterize the horizon's shape by $r = h(\text{angle})$ for some single-valued \defn{horizon shape function} $h$ defined on the 2-sphere $S^2$. -We then write~\eqref{AEIDevelopment_AHFinderDirect_eqn-horizon} as a -2-D elliptic PDE on $S^2$ for the function $h$. We finite difference +I then write~\eqref{AEIDevelopment_AHFinderDirect_eqn-horizon} as a +2-D elliptic PDE on $S^2$ for the function $h$. I finite difference this in angle to obtain a system of simultaneous nonlinear algebraic equations for $h$ at the angular grid points, and solve this system of equations by a global Newton's method (or a variant with improved convergence). -We use a multiple grid patch system to cover $S^2$ without coordinate +I use a multiple grid patch system to cover $S^2$ without coordinate singularities. In general there are 6~patches, one each covering a neighborhood of the $\pm z$, $\pm x$, and $\pm y$ axes, but if the slice has suitable symmetries, this may be reduced to 5, 4, or 3~patches. @@ -213,20 +210,12 @@ Computationally, this algorithm has 3 main parts: \begin{itemize} \item Computation of the ``horizon function'' $H(h)$ given a trial surface defined by a trial horizon shape function $h$. This is - done by interpolating $g_\ij$ and $K_\ij$ from the 3-D $xyz$ grid + done by interpolating the Cactus geometry fields $g_\ij$ and + $K_\ij$ (and optionally $\psi$) from the 3-D $xyz$ grid to the (2-D set of) trial-horizon-surface grid points (also computing $\partial_k g_\ij$ in the interpolation process), - then doing all further computations solely at the horizon-surface - grid points.%%% -\footnote{%%% - The code for the relativity computations - (\ie{}~the apparent horizon equation itself) - is mainly machine-generated from Maple code, - which in turn uses a Perl preprocessor. - You don't need to have Maple installed - unless you want to modify the relativity - computations.%%% - }%%% + then doing all further computations with angular grid functions + defined solely on $S^2$ (\ie{} at the horizon-surface grid points). \item Computation of the Jacobian matrix $\Jac[H(h)]$ of $H(h)$. This thorn incorporates the \defn{symbolic differentiation} technique described in @@ -251,16 +240,27 @@ Computationally, this algorithm has 3 main parts: \subsection{Obtaining and Compiling \thorn{AHFinderDirect}} You should be able to obtain the source code for this thorn via the -usual procedures (\eg{}~cvs checkout) for the \arrangement{AEIDevelopment} -arrangement. +usual procedures (\eg{}~cvs checkout); at present it lives in the +\arrangement{AEIDevelopment} arrangement. This thorn is written primarily in \Cplusplus{}, calling C and -Fortran~77 numerical libraries. In theory the code should be quite -portable to modern \Cplusplus{} compilers, but in practice I've had -a number of portability problems with various compilers. See the -``Code Notes'' and ``CompilerNotes'' sections in the top-level -\code{README} file for details and lists of compilers currently -known to be ok or not. +Fortran~77 numerical libraries.%%% +\footnote{%%% + The (C) code for the relativity computations + (\ie{}~the apparent horizon equation itself) + is mainly machine-generated from Maple code, + which in turn uses a Perl preprocessor. + But the machine-generated C code is already + in CVS along with the rest of this thorn's + source code, so you don't need to have Maple + installed unless you want to modify the + relativity computations.%%% + }%%% +{} In theory the code should be quite portable to modern \Cplusplus{} +compilers, but in practice I've had a number of portability problems +with various compilers. See the ``Code Notes'' and ``Compiler Notes'' +sections in the top-level \code{README} file for details and lists of +compilers currently known to be ok or not. To compile (a Cactus configuration which includes) this thorn, you must set the environment variable \code{LAPACK\_DIR}, and possibly @@ -270,131 +270,453 @@ section in the top-level \code{README} file for details. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{What \thorn{AHFinderDirect} Needs} + +Your Cactus configuration and run must satisfy a number of requirements +in order to use \thorn{AHFinderDirect}: +\begin{itemize} +\item You should use a current-CVS checkout of the Cactus flesh + and of all relevant thorns. I haven't tested \thorn{AHFinderDirect} + at all with older versions of the flesh or other thorns. +\item Obviously, your Cactus configuration must include + \thorn{AHFinderDirect}, and your \code{ActiveThorns} parameter(s) + must activate it. \thorn{AHFinderDirect} inherits from \thorn{Grid}, + \thorn{ADMBase}, and \thorn{StaticConformal}, so you'll need + those (or more precisely some thorns providing them), too. +\item The \verb|ADMBase::metric_type| values \verb|"physical"| and + \verb|"static conformal"| are supported; for the latter you must + have storage turned on for at least the conformal factor + \verb|StaticConformal::psi|. (The Cactus 3-D grid functions + for 1st and 2nd derivatives of \verb|psi| aren't used.) +\item \thorn{AHFinderDirect} uses the new \verb|CCTK_InterpLocalUniform()| + interpolator API, which at present is only supported by + \thorn{LocalInterp}, so you need that thorn compiled in to + your configuration and activated. +\item At present \thorn{AHFinderDirect} only works for single-processor + Cactus runs. This isn't checked, so if you try to activate + it in a multi-procssor run you'll probably get garbage results. + I hope to properly support multi-processor operation soon. +\end{itemize} + +There are also some restrictions on the spacetime, or more precisely +on each slice where you want to find apparent horizons: +\begin{itemize} +\item At present only \verb|Grid::domain = "full"| and + \verb|Grid::domain = "bitant"| grids are supported. + I hope to support other symmetry types soon. +\item \thorn{AHFinderDirect} requires that the Cactus geometry + ($g_{ij}$, $K_{ij}$, and optionally $\psi$) be nonsingular + in a neighborhood of the apparent horizon. In particular, + this means that it quite certainly will {\em not\/} work for + spacetimes/slicings which have a singular geometry on the + horizon, such as Schwarzschild/Schwarzschild and + Kerr/Boyer-Lindquist.%%% +\footnote{%%% + Nonsingular slicings of those same spacetimes, + such as Schwarzschild/Eddington-Finkelstein, + Kerr/Kerr, and Kerr/Kerr-Schild, are fine, and + are in fact nice test cases. + }%%% +\item Less obviously, this also means that if there is a + singularity in the geometry somewhere near the apparent + horizon, then you need to have a high enough Cactus 3-D grid + resolution that the geometry interpolation doesn't ``see'' + the singularity. For example, the initial data parameters + \begin{verbatim} + ADMBase::initial_data = "misner_bh" + IDAnalyticBH::mu = 2.0 + ADMBase::initial_lapse = "Cadez" + \end{verbatim} + specify Misner data with $\mu=2$, using the \v{C}ade\v{z} + slicing. This geometry has a singularity at $z = \pm 1$ + on the $z$~axis. With \verb|grid::dxyz = 0.040| or smaller, + \thorn{AHFinderDirect} has no problems finding the apparent + horizons (which have centroid $z = \pm 1.03077$ and radia + roughtly 0.28), but with \verb|grid::dxyz = 0.050| or larger, + \thorn{AHFinderDirect} fails to find the horizon after finding + \verb|NaN| and infinity values in the interpolated geometry + close to the pole. Another failure mode which + \thorn{AHFinderDirect} may report in such a situation + (where the Cactus 3-D grid resolution is too low) is that + the interpolated $g_{ij}$ fails to be positive definite. +\item At the moment \thorn{AHFinderDirect} and \thorn{LocalInterp} + don't know anything about excision, so if the apparent horizon + (or any trial horizon surface as the algorithm is iterating + towards the apparent horizon) gets too close to an excised + region, you'll get garbage results as the interpolator tries + to interpolate data from the excised region. I hope to + properly support excision (at least in the sense of checking + for the trial horizon surface being too close to an excised + region) soon. +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \subsection{Parameters} This thorn has lots of parameters, but most of them have reasonable -default values which you probably won't need to change. But you will -probably need to set the following parameters explicitly -(see the \code{param.ccl} file for details): +default values which you probably won't need to change. Here I describe +the parameters which you are likely to want to at least look at, and +possibly set explicitly. + +Note that all of the ``\code{[}$n$\code{]}'' parameters are Cactus +array parameters, which you need to specify separately in your parameter +file for each apparent horizon. If this isn't clear, see the the +examples in section~\ref{AEIDevelopment_AHFinderDirect_sect-examples}. + +%%%%%%%%%%%%%%%%%%%% + +\subsubsection{Overall Parameters} + \begin{description} \item[%%% - \begin{tabular}{l} + \begin{tabular}{@{}l@{}} \code{find\_AHs\_at\_postinitial} \\ \code{find\_AHs\_at\_poststep} %%%\\ \end{tabular} - ]\mbox{}\\ - Do you want to find apparent horizons in the initial data, - at each time step of a time evolution, or both (the default)? + ] +\mbox{}\\ + Do you want to find apparent horizons in the initial data + (at the \code{POSTINITIAL} Cactus schedule bin), + at each time step of a time evolution + (at the \code{POSTSTEP} Cactus schedule bin), + or both (the default)? \item[\code{N\_horizons}] +\mbox{}\\ How many apparent horizons do you want to find in each slice? Typical values are 1 (the default), 2 (for binary black hole systems), and 3 (for binary black hole systems where you expect to evolve long enough to also see a common apparent horizon). This thorn - numbers the apparent horizons are numbered from 1 to - \code{N\_horizons} inclusive. -\item[\code{initial\_guess\_method}] - This controls the initial guess for each apparent horizon - position.%%% -\footnote{%% - This is used the first time we try to find any - given apparent horizon, and also any succeeding - time when the most recent attempt to find this - apparent horizon failed. If we succeed in finding - an apparent horizon, than that apparent horizon - position is used as the initial guess the next - time we try to find this same apparent horizon. - }%%% -{} This can either be read from an input file or files, set to - the (analytical) event horizon of a Kerr spacetime in either - Kerr or Kerr-Schild coordinates, or set to a specified coordinate - sphere or ellipsoid. For most of these cases there are - additional parameters to specify details of the initial - data: -\item[%%% - \begin{tabular}{@{}l@{}} - \code{initial\_guess\_\_Kerr\_Kerr\_\_x\_posn[}$n$\code{]} \\ - \code{initial\_guess\_\_Kerr\_Kerr\_\_y\_posn[}$n$\code{]} \\ - \code{initial\_guess\_\_Kerr\_Kerr\_\_z\_posn[}$n$\code{]} \\ - \code{initial\_guess\_\_Kerr\_Kerr\_\_mass[}$n$\code{]} \\ - \code{initial\_guess\_\_Kerr\_Kerr\_\_spin[}$n$\code{]} %%%\\ - \end{tabular}%%% - ]\mbox{}\\ - These are parameters for - \verb|initial_guess_method = "Kerr/Kerr"|. -\item[%%% - \begin{tabular}{@{}l@{}} - \code{initial\_guess\_\_Kerr\_KerrSchild\_\_x\_posn[}$n$\code{]} \\ - \code{initial\_guess\_\_Kerr\_KerrSchild\_\_y\_posn[}$n$\code{]} \\ - \code{initial\_guess\_\_Kerr\_KerrSchild\_\_z\_posn[}$n$\code{]} \\ - \code{initial\_guess\_\_Kerr\_KerrSchild\_\_mass[}$n$\code{]} \\ - \code{initial\_guess\_\_Kerr\_KerrSchild\_\_spin[}$n$\code{]} %%%\\ - \end{tabular}%%% - ]\mbox{}\\ - These are parameters for - \verb|initial_guess_method = "Kerr/Kerr-Schild"|. -\item[%%% - \begin{tabular}{@{}l@{}} - \code{initial\_guess\_\_sphere\_\_x\_center[}$n$\code{]} \\ - \code{initial\_guess\_\_sphere\_\_y\_center[}$n$\code{]} \\ - \code{initial\_guess\_\_sphere\_\_z\_center[}$n$\code{]} \\ - \code{initial\_guess\_\_sphere\_\_radius[}$n$\code{]} %%%\\ - \end{tabular}%%% - ]\mbox{}\\ - These are parameters for - \verb|initial_guess_method = "sphere"|. + numbers the apparent horizons from 1 to \code{N\_horizons} inclusive. + There are a number of other parameters (described below) + which you need to set for of these each apparent horizons. + + Note that \code{N\_horizons} sets the number of apparent horizons + you want to find {\em in the Cactus 3-D numerical grid\/}, not in + the whole spacetime. For example, if you are simulating (say) + Misner data with \verb|Grid::domain = "bitant"|, with the two + throats at (say) roughly $z = \pm 1$, then you should set + \verb|N_horizons = 1|, since you're only finding a single + apparent horizon within the numerical grid. Similarly, + to evolve such a slice to a final near-static state with a + common horizon centered on the origin, you should set + \verb|N_horizons = 2|, since you're finding at most 2 + apparent horizons within the numerical grid (the initial-slice + one centered near $z = +1$ and the final common one). +\item[\code{verbose\_level}] +\mbox{}\\ + This controls how verbose this thorn is in printing + informational (non-error) messages describing what it's + doing. In order from tersest to most verbose, the allowable + values are + \begin{description} + \item[\code{"physics highlights"}] + \mbox{}\\ + Print only a line or two each time + \thorn{AHFinderDirect} runs, giving the + number of horizons found and their irreducible masses. + (This doesn't work yet.) + \item[\code{"physics details"}] + \mbox{}\\ + Give more detailed description of each horizon found, + including area, centroid position, and irreducible mass. + \item[\code{"algorithm highlights"}] + \mbox{}\\ + Also print a single line for each Newton iteration giving + the 2-norm and $\infty$-norm of the $H(h)$ function defined + by~\eqref{AEIDevelopment_AHFinderDirect_eqn-horizon}. + This is the default. + \item[\code{"algorithm details"}] + \mbox{}\\ + Print lots of detailed messages tracing what the code + is doing. + \end{description} +\end{description} + +%%%%%%%%%%%%%%%%%%%% + +\subsubsection{Choosing the Local Coordinate Origins (Expansion Centers)} + +For each apparent horizon you want to find, you need to specify +the Cactus $(x,y,z)$ coordinates of a local coordinate system origin. +As described in +section~\ref{AEIDevelopment_AHFinderDirect_sect-how-ahfinderdirect-works}, +each apparent horizon must be a Strahlk\"{o}rper with respect to its +local coordinate system origin. + +You specify the local coordinate system origins with the (Cactus array) +parameters +\begin{description} \item[%%% \begin{tabular}{@{}l@{}} - \code{initial\_guess\_\_ellipsoid\_\_x\_center[}$n$\code{]} \\ - \code{initial\_guess\_\_ellipsoid\_\_y\_center[}$n$\code{]} \\ - \code{initial\_guess\_\_ellipsoid\_\_z\_center[}$n$\code{]} \\ - \code{initial\_guess\_\_ellipsoid\_\_x\_radius[}$n$\code{]} \\ - \code{initial\_guess\_\_ellipsoid\_\_y\_radius[}$n$\code{]} \\ - \code{initial\_guess\_\_ellipsoid\_\_z\_radius[}$n$\code{]} \\ - \end{tabular}%%% - ]\mbox{}\\ - These are parameters for - \verb|initial_guess_method = "ellipsoid"|. - - All of the ``\code{[}$n$\code{]}'' parameters are Cactus array - parameters, \ie{} you need to specify them separately in your - parameter file for each apparent horizon you're searching for. - For example, the parameters -\begin{verbatim} -AHFinderDirect::N_horizons = 2 -AHFinderDirect::initial_guess_method = "sphere" -AHFinderDirect::initial_guess__sphere__x_center[1] = 0.0 -AHFinderDirect::initial_guess__sphere__y_center[1] = 5.0 -AHFinderDirect::initial_guess__sphere__z_center[1] = 0.0 -AHFinderDirect::initial_guess__sphere__radius[1] = 2.0 -AHFinderDirect::initial_guess__sphere__x_center[2] = -10.0 -AHFinderDirect::initial_guess__sphere__y_center[2] = 0.0 -AHFinderDirect::initial_guess__sphere__z_center[2] = 2.0 -AHFinderDirect::initial_guess__sphere__radius[2] = 1.5 -\end{verbatim} - would specify initial guesses for 2 horizons: - horizon~\#1 a coordinate sphere of radius~$2$ at $(0,5,0)$, and - horizon~\#2 a coordinate sphere of radius~$1.5$ at $(-10,0,2)$. - - For the Kerr parameters, note that this thorn always uses - the convention that the spin parameter $a \equiv J/m^2$ is - dimensionless. + \code{origin\_x[}$n$\code{]} \\ + \code{origin\_y[}$n$\code{]} \\ + \code{origin\_z[}$n$\code{]} %%%\\ + \end{tabular} + ] +\mbox{}\\ + These all default to 0.0. + In practice, you should set these parameters to be somewhere + reasonably close to your best guess for the center of each apparent + horizon. These aren't {\em too\/} critical: being off by 1/4 + of the horizon radius is no problem, and -- assuming the algorithm + still converges -- even 1/2 of the horizon radius only slows + the convergence by an extra iteration or two. But poor values + of these parameters do make the algorithm more likely to fail + to converge. \end{description} -While it's not required, you may also want to set the -\code{verbose\_level} parameter. This controls how verbose this thorn -is in printing informational (non-error) messages describing what it's -doing; this can vary from {\em very\/} verbose to quite terse. -See the \code{param.ccl} file for details. +At present the local coordinate origin is fixed once you set it; +there's no provision for it to move to track a moving black hole. +I hope to add such a provision soon.%%% +\footnote{%%% + This would be along the lines of the + \thorn{AHFinder} apparent horizon finder's + \code{AHFinder::ahf\_wander = "true"} + option. + }%%% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%% + +\subsubsection{Specifying the Initial Guess} + +\thorn{AHFinderDirect} requires an initial guess +for the apparent horizon's coordinate position and shape +(that is, for the $h(\text{angle})$ function defined in +section~\ref{AEIDevelopment_AHFinderDirect_sect-how-ahfinderdirect-works}) +for each apparent horizon you want to find. If there really is an +apparent horizon present, and this initial guess is within some radius +of convergence (typically on the order of 1/2 of the horizon radius) +of the apparent horizon, then this thorn will probably find the +apparent horizon. If not, then this thorn will fail to converge; +there's no way to distinguish this case from the one where there's +actually no apparent horizon present. + +The ``initial guess'' specification is used the first time we try to +find any given apparent horizon, and also any succeeding time when the +most recent attempt to find this apparent horizon failed. If we succeed +in finding a given apparent horizon, than that apparent horizon position +is automatically reused as the initial guess the next time we try to +find the same apparent horizon; in this case the explicit ``initial guess'' +specification is ignored.%%% +\footnote{%%% + This is similar to the \thorn{AHFinder} apparent + horizon finder's behavior with the + \code{AHFinder::ahf\_guessold = "true"} + option. + }%%% -\subsection{Black Hole Diagnostics} +There are a number of parameters for specifying the initial guess: +\begin{description} +\item[\code{initial\_guess\_method}] +\mbox{}\\ + This sets what type of the initial guess is used for each + apparent horizon position.%%% +\footnote{%%% + At the moment \code{initial\_guess\_method} is + a single parameter which applies to all apparent + horizons. This might change (to it being a Cactus + array parameter to be set separately for each + apparent horizon) if there's popular demand\dots + }%%% +{} There are several possibilities, most with their own sets + of subparameters:%%% +\footnote{%%% + The naming scheme for these is similar to + that used in the \thorn{Exact} thorn. + }%%% +$^,$%%% +\footnote{%%% + For the Kerr parameters, note that this thorn + always uses the convention that the spin parameter + $a \equiv J/m^2$ is dimensionless. + }%%% + \begin{description} + \item[\code{"read from file"}] + \mbox{}\\ + This reads the initial-guess $h(\text{angle})$ function + from a data file. The file format is currently hard-wired + to be that written with \verb|file_format = "ASCII (gnuplot)"| + (see below). + \item[\code{"Kerr/Kerr"}] + \mbox{}\\ + This sets the initial guess to the analytically-known + apparent horizon position in a Kerr spacetime + in Kerr coordinates; there are subparameters + \begin{description} + \item[%%% + \begin{tabular}{@{}l@{}} + \code{initial\_guess\_\_Kerr\_Kerr\_\_x\_posn[}$n$\code{]} \\ + \code{initial\_guess\_\_Kerr\_Kerr\_\_y\_posn[}$n$\code{]} \\ + \code{initial\_guess\_\_Kerr\_Kerr\_\_z\_posn[}$n$\code{]} %%%\\ + \end{tabular}%%% + ] + \mbox{}\\ + to set the position of the Kerr black hole, and + \item[%%% + \begin{tabular}{@{}l@{}} + \code{initial\_guess\_\_Kerr\_Kerr\_\_mass[}$n$\code{]} \\ + \code{initial\_guess\_\_Kerr\_Kerr\_\_spin[}$n$\code{]} %%%\\ + \end{tabular}%%% + ] + \mbox{}\\ + to set its mass and spin. + \end{description} + \item[\code{"Kerr/Kerr-Schild"}] + \mbox{}\\ + This sets the initial guess to the analytically-known + apparent horizon position in a Kerr spacetime + in Kerr-Schild coordinates; there are subparameters + \begin{description} + \item[%%% + \begin{tabular}{@{}l@{}} + \code{initial\_guess\_\_Kerr\_KerrSchild\_\_x\_posn[}$n$\code{]} \\ + \code{initial\_guess\_\_Kerr\_KerrSchild\_\_y\_posn[}$n$\code{]} \\ + \code{initial\_guess\_\_Kerr\_KerrSchild\_\_z\_posn[}$n$\code{]} %%%\\ + \end{tabular}%%% + ] + \mbox{}\\ + to set the position of the Kerr black hole, and + \item[%%% + \begin{tabular}{@{}l@{}} + \code{initial\_guess\_\_Kerr\_KerrSchild\_\_mass[}$n$\code{]} \\ + \code{initial\_guess\_\_Kerr\_KerrSchild\_\_spin[}$n$\code{]} %%%\\ + \end{tabular}%%% + ] + \mbox{}\\ + to set its mass and spin. + \end{description} + \item[\code{"coordinate sphere"}] + \mbox{}\\ + This sets the initial guess to a coordinate sphere; + there are subparameters + \begin{description} + \item[%%% + \begin{tabular}{@{}l@{}} + \code{initial\_guess\_\_coord\_sphere\_\_x\_center[}$n$\code{]} \\ + \code{initial\_guess\_\_coord\_sphere\_\_y\_center[}$n$\code{]} \\ + \code{initial\_guess\_\_coord\_sphere\_\_z\_center[}$n$\code{]} %%%\\ + \end{tabular}%%% + ] + \mbox{}\\ + to set the center position, and + \item[\code{initial\_guess\_\_coord\_sphere\_\_radius[}$n$\code{]}] + \mbox{}\\ + to set the radius. + \end{description} + \item[\code{"coordinate ellipsoid"}] + \mbox{}\\ + This sets the initial guess to a coordinate ellipsoid; + there are subparameters + \begin{description} + \item[%%% + \begin{tabular}{@{}l@{}} + \code{initial\_guess\_\_coord\_ellipsoid\_\_x\_center[}$n$\code{]} \\ + \code{initial\_guess\_\_coord\_ellipsoid\_\_y\_center[}$n$\code{]} \\ + \code{initial\_guess\_\_coord\_ellipsoid\_\_z\_center[}$n$\code{]} %%%\\ + \end{tabular}%%% + ] + \mbox{}\\ + to set the center position, and + \item[\code{initial\_guess\_\_coord\_ellipsoid\_\_x\_radius[}$n$\code{]}] + \item[\code{initial\_guess\_\_coord\_ellipsoid\_\_y\_radius[}$n$\code{]}] + \item[\code{initial\_guess\_\_coord\_ellipsoid\_\_z\_radius[}$n$\code{]}] + \mbox{}\\ + to set the radia (semimajor axes). + \end{description} + \end{description} +\end{description} + +%%%%%%%%%%%%%%%%%%%% + +\subsubsection{I/O Parameters} The main output of this thorn is the computed horizon shape function $h({\rm angle})$, and correspondingly the $(x,y,z)$ coordinate positions -of the horizon-surface angular grid points. These are typically computed -very accurately; tests on Kerr spacetimes give typical errors of $10^{-4}m$ -to $10^{-5}m$. +of the apparent-horizon-surface (angular) grid points. There are several +parameters controlling if and how these should be written to data files: + +\begin{description} +\item[\code{file\_format}] +\mbox{}\\ + This specifies the file format for $h$ (and other + angular-grid-function) data files. Unfortunately, at the + moment only a single format is implemented, + \begin{description} + \item[\code{"ASCII (gnuplot)"}] + \mbox{}\\ + This is a simple ASCII format designed for easy + plotting with gnuplot: + \begin{itemize} + \item At each Cactus time step, each apparent horizon + is written to a separate data file. The time + step number and the apparent horizon number + are both encoded in the file name; the actual + file name is given by a \verb|printf()| format + \verb|"%s.t%d.ah%d.%s"|, where + \begin{itemize} + \item the first \verb|%s| is the base file name + set by the \verb|h_base_file_name| + parameter (see below) + \item the first \verb|%d| is the + Cactus time step number + \item the second \verb|%d| is the + apparent horizon number + \item the second \verb|%s| is the + file name extension, which defaults to + \verb|gnuplot| (see the \verb|param.ccl| + file if you want to change this) + \end{itemize} + \item Comment lines begin with \verb|#|. + \item Patches are separated by 2 blank lines; + rows of apparent-horizon points within a patch + are separated by single blank lines. + \item Each apparent-horizon-surface point + is described by a single line, containing + the whitespace-separated fields + \begin{itemize} + \item Two ``unwrapped'' angular coordinates + in degrees, representing a point on $S^2$. + \item The $h$ value, giving the radius + of the apparent horizon surface + at that angle. + \item The corresponding Cactus $(x,y,z)$ + coordinates. + \end{itemize} + \end{itemize} + Given such a data file \verb|"h.dat"|, the gnuplot + command + \begin{verbatim} + splot 'h.dat' + \end{verbatim} + will plot the $h(\text{angle})$ function, with the + $x$ and $y$ axes of the plot being the two ``unwrapped'' + angular coordinates on $S^2$, in degrees, and the + $z$ axis being $h(\text{angle})$. The gnuplot command + \begin{verbatim} + splot 'h.dat' using 4:5:6 + \end{verbatim} + will plot the apparent horizon surface in 3-D. + \end{description} +\item[\code{how\_often\_to\_output\_h}] +\mbox{}\\ + This parameter controls how often \thorn{AHFinderDirect} + writes $h$ and other ``large'' \verb|file_format|-format + data files: it only writes them if this parameter + is nonzero, and the Cactus time step number is an + integral multiple of this parameter. +\item[\code{h\_base\_file\_name}] +\mbox{}\\ + This specifies the base file name for $h$ data files, as + described above. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Accuracy and Diagnostics} + +The apparent horizon positions are typically computed very accurately; +tests on Kerr spacetimes give typical errors of $10^{-4}m$ to $10^{-5}m$. This thorn also prints various messages to standard output, as controlled by the \code{verbose\_level} parameter. In particular, @@ -417,6 +739,99 @@ at some point this thorn may be enhanced to do this. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Examples} +\label{AEIDevelopment_AHFinderDirect_sect-examples} + +There are a few example parameter files in the \code{par/} directory, +including Kerr initial data, Misner initial data, and Misner time-evolution +tests. The \verb|Kerr-tiny.par| parameter file is close to a minimal +\thorn{AHFinderDirect} example: + +\begin{verbatim} +# This parameter file sets up Kerr/Kerr-Schild initial data, then +# finds the apparent horizon in it. The local coordinate system origin +# and the initial guess are both deliberately de-centered with respect +# to the black hole, to make this a non-trivial test for the apparent +# horizon finder. +# +# This parameter is "tiny" in the sense that it sets only a small number +# of AHFinderDirect parameters. + +# next two lines is actually one long line +# (Cactus doesn't seem to grok \-newline continuation here :( :( ) +ActiveThorns = "CartGrid3D LocalInterp PUGH ADMBase ADMCoupling \ + StaticConformal CoordGauge Exact AHFinderDirect" + +# flesh +cactus::cctk_itlast = 0 + +# PUGH +driver::ghost_size = 2 +driver::global_nx = 31 +driver::global_ny = 31 +driver::global_nz = 17 + +# CartGrid3D +grid::domain = "bitant" +grid::avoid_origin = "false" +grid::type = "byspacing" +grid::dxyz = 0.2 + +# ADMBase +ADMBase::initial_lapse = "exact" +ADMBase::initial_shift = "exact" +ADMBase::initial_data = "exact" +ADMBase::lapse_evolution_method = "static" +ADMBase::shift_evolution_method = "static" +ADMBase::metric_type = "physical" + +# Exact +Exact::exact_model = "Kerr/Kerr-Schild" +Exact::Kerr_KerrSchild__mass = 1.0 +Exact::Kerr_KerrSchild__spin = 0.6 + +######################################## + +AHFinderDirect::find_AHs_at_poststep = "false" # no time evolution +AHFinderDirect::h_base_file_name = "Kerr-tiny.h" + +AHFinderDirect::N_horizons = 1 +AHFinderDirect::origin_x[1] = 0.5 +AHFinderDirect::origin_y[1] = 0.7 +AHFinderDirect::origin_z[1] = 0.0 + +AHFinderDirect::initial_guess_method = "coordinate sphere" +AHFinderDirect::initial_guess__coord_sphere__x_center[1] = -0.2 +AHFinderDirect::initial_guess__coord_sphere__y_center[1] = 0.3 +AHFinderDirect::initial_guess__coord_sphere__z_center[1] = 0.0 +AHFinderDirect::initial_guess__coord_sphere__radius[1] = 2.0 +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Other Related Thorns} + +If you're interested in \thorn{AHFinderDirect}, you might also be +interested in some other related thorns: + +\begin{description} +\item[\thorn{EHFinder}] (in the \arrangement{AEIDevelopment} arrangement) + was written by Peter Diener, and finds the {\em event\/} horizon(s) + in a numerically computed spacetime. +\item[\thorn{AHFinder}] (in the \arrangement{CactusEinstein} arrangement) + was written by Miguel Alcubierre, and includes two different + algorithms for finding apparent horizons, a minimization method + and a ``fast flow'' method based on +\cite{AEIDevelopment_AHFinderDirect_Gundlach-1998-apparent-horizon-finding}. + Unfortunately, both methods are very slow in practice. +\item[\thorn{TGRapparentHorizon2D}] (in the \arrangement{TAT} arrangement) + was written by Erik Schnetter, and is another apparent horizon + finder. It uses methods very similar to this thorn, and (like + this thorn) is very fast and accurate. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + % make LaTeX read in ahfinderdirect.bbl produced by bibtex % run 'make bib' in this directory to update this \bibliography{ahfinderdirect} |