* 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

1 files changed, 63 insertions, 34 deletions

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