From 7505fceeac8965e2c26eb1762bdc03dc64118689 Mon Sep 17 00:00:00 2001 From: jthorn Date: Wed, 23 Jun 2004 13:43:23 +0000 Subject: * fix description of output_every parameter * add new section on "Visualization", including gnuplot and OpenDX stuff (with a pointer to Thomas Radke's OpenDX macros in cvs) git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/AHFinderDirect/trunk@1371 f88db872-0e4f-0410-b76b-b9085cfa78c5 --- doc/documentation.tex | 97 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 63 insertions(+), 34 deletions(-) (limited to 'doc') diff --git a/doc/documentation.tex b/doc/documentation.tex index e2d32a7..86468c9 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -106,6 +106,7 @@ \def\defn#1{``#1''} % definition of a term \def\arrangement#1{{\bf #1}} % name of an arrangement \def\thorn#1{{\bf #1}} % name of a thorn +\def\program#1{{\bf #1}} % name of computer program \def\cvsplace#1{{\bf #1}} % name of a CVS repository/directory/tag \def\cf{\hbox{cf.\hbox{}}} \def\eg{\hbox{eg.\hbox{}}} @@ -185,8 +186,8 @@ Besides this thorn guide, the other main sources of information on the paper \cite{AEIThorns/AHFinderDirect/Thornburg2003:AH-finding}, and to a lesser extent the paper \cite{AEIThorns/AHFinderDirect/Thornburg-1996-apparent-horizon-finding}. -As a courtesy, I ask that these papers be cited in any published research -which uses this thorn, or which uses code from this thorn. +As a courtesy, I ask that both these papers be cited in any published +research which uses this thorn, or which uses code from this thorn. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -690,17 +691,18 @@ to data files: \begin{description} \item[\code{output\_h\_every}] \mbox{}\\ - If \verb|find_AHs_at_poststep| is set to true, + As described in + section~\ref{AHFinderDirect/sect-parameters/overall-parameters}, \thorn{AHFinderDirect} will try to find the apparent horizon(s) - at every time step. However, you can control how often - (if at all) the apparent horizon shape(s) are written to - data files: this is only done if \verb|output_h_every| + every \verb|find_every| time steps. However, you can control + how often (if at all) the apparent horizon shape(s) are written + to data files: this is only done if \verb|output_h_every| is nonzero, and the Cactus time step number \verb|cctk_iteration| - is an integral multiple of this parameter. + is an integral multiple of this parameter (\verb|output_h_every|). \item[\code{file\_format}] \mbox{}\\ - This specifies the file format for $h$ (and other + This specifies the file format for horizon-shape (and other angular-grid-function) data files. Unfortunately, at the moment only a single format is implemented, \begin{description} @@ -752,30 +754,9 @@ to data files: 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. - - Alternatively, you can visualize the horizon surface(s) - using OpenDX, using Thomas Radke's import macros from - the \cvsplace{AEIPhysics} repository. These are in - the \cvsplace{Visualization/OpenDX/Macros/} directory, - under the names \cvsplace{ImportAHFinderDirectGnuplot.net} - and \cvsplace{ImportAHFinderDirectGnuplotPatch.net}. - They use a set of ``control files'' named \verb|*.dx|, - one per horizon, which \thorn{AHFinderDirect} (by default) - writes into the same directory as the main - apparent-horizon--shape output files. + See section~\ref{AHFinderDirect/sect-visualization} + for a discussion of visualization for these and other + \thorn{AHFinderDirect} output files. \end{description} \item[\code{h\_directory}] @@ -1481,6 +1462,54 @@ prints its mean radius,%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Visualization} +\label{AHFinderDirect/sect-visualization} + +There are several ways to visualize \thorn{AHFinderDirect}'s output: + +The simplest is to plot various quantities from the +\verb|BH_diagnostics| files (described in detail in +section~\ref{AHFinderDirect/sect-parameters/BH-diagnostics-parameters}). +For example, using gnuplot (\verb|http://www.gnuplot.info|), you can +plot a graph of the surface area of horizon \#4 as a function of +coordinate time, with the command +\begin{verbatim} +plot 'BH_diagnostics.ah4.gp' using 2:26 with points +\end{verbatim} +ygraph (\verb|http://www.aei.mpg.de/~pollney/ygraph/|) may also be +able to directly plot the \verb|BH_diagnostics| files. + +Given a horizon-shape data file \verb|h.t105.h4.gp|, the gnuplot +command +\begin{verbatim} +splot 'h.t105.h4.gp' with lines +\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})$. However, +in practice this usually isn't very informative. Instead, you +probably want the gnuplot command +\begin{verbatim} +splot 'h.t105.h4.gp' using 4:5:6 with lines +\end{verbatim} +which will plot the 3-D shape of the apparent horizon surface. + +Another Visualization option is OpenDX (\verb|http://www.opendx.org/|). +Thomas Radke's has written some OpenDX macros +\program{ImportAHFinderDirectGnuplot.net} +and \program{ImportAHFinderDirectGnuplotPatch.net} +to import \thorn{AHFinderDirect} horizon-shape data files. +These macros use a set of ``control files'' named \verb|*.dx|, +one per horizon, which \thorn{AHFinderDirect} (by default) writes +into the same directory as the main horizon--shape output files. +You can get these macros by anonymous CVS with the command +\begin{verbatim} +cvs -d :pserver:cvs_anon@cvs.aei.mpg.de:/numrelcvs \ + checkout AEIPhysics/Visualization/OpenDX +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \section{Accuracy} The apparent horizon positions are typically computed very accurately; @@ -1574,8 +1603,8 @@ AHFinderDirect::initial_guess__coord_sphere__radius[1] = 2.0 \section{How \thorn{AHFinderDirect} Works} \label{AHFinderDirect/sect-how-ahfinderdirect-works} -\thorn{AHFinderDirect} uses the apparent horizon (henceforth \defn{horizon}) -finding algorithm of +\thorn{AHFinderDirect} uses the apparent horizon +(henceforth \defn{horizon}) finding algorithm of \cite{AEIThorns/AHFinderDirect/Thornburg-1996-apparent-horizon-finding}, modified slightly to work with $g_\ij$ and $K_\ij$ on a Cartesian ($xyz$) grid. The algorithm is described in detail in -- cgit v1.2.3