document parameters for setting an (excision) mask gridfn

based on the horizon shape


git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/AHFinderDirect/trunk@992 f88db872-0e4f-0410-b76b-b9085cfa78c5

1 files changed, 140 insertions, 40 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 5e3aff7..351940c 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -340,10 +340,10 @@ this clear.
 
 \begin{description}
 \item[%%%
-      \begin{tabular}{@{}l@{}}
-      \code{find\_AHs\_at\_postinitial}	\\
-      \code{find\_AHs\_at\_poststep}	%%%\\
-      \end{tabular}
+     \begin{tabular}{@{}l@{}}
+     \code{find\_AHs\_at\_postinitial}	\\
+     \code{find\_AHs\_at\_poststep}	%%%\\
+     \end{tabular}
      ]
 \mbox{}\\
 	These are Boolean parameters specifying whether
@@ -429,11 +429,11 @@ You specify the local coordinate system origins with the (Cactus array)
 parameters
 \begin{description}
 \item[%%%
-      \begin{tabular}{@{}l@{}}
-      \code{origin\_x[}$n$\code{]}	\\
-      \code{origin\_y[}$n$\code{]}	\\
-      \code{origin\_z[}$n$\code{]}	%%%\\
-      \end{tabular}
+     \begin{tabular}{@{}l@{}}
+     \code{origin\_x[}$n$\code{]}	\\
+     \code{origin\_y[}$n$\code{]}	\\
+     \code{origin\_z[}$n$\code{]}	%%%\\
+     \end{tabular}
      ]
 \mbox{}\\
 	These all default to 0.0.
@@ -521,19 +521,19 @@ $^,$%%%
 		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}%%%
+		     \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}%%%
+		     \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.
@@ -545,19 +545,19 @@ $^,$%%%
 		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}%%%
+		     \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}%%%
+		     \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.
@@ -568,11 +568,11 @@ $^,$%%%
 		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}%%%
+		     \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
@@ -586,17 +586,21 @@ $^,$%%%
 		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}%%%
+		     \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{]}]
+		\item[%%%
+		     \begin{tabular}{@{}l@{}}
+		     \code{initial\_guess\_\_coord\_ellipsoid\_\_x\_radius[}$n$\code{]}
+		     \code{initial\_guess\_\_coord\_ellipsoid\_\_y\_radius[}$n$\code{]}
+		     \code{initial\_guess\_\_coord\_ellipsoid\_\_z\_radius[}$n$\code{]}
+		     \end{tabular}%%%
+		     ]
 		\mbox{}\\
 			to set the radia (semimajor axes).
 		\end{description}
@@ -771,15 +775,111 @@ controlled by the following parameters:
 	\end{itemize}
 
 \item[\code{BH\_diagnostics\_base\_file\_name}]
+\mbox{}\\
 	This specifies the base file name for black hole diagnostics
 	data files, as described above.  This defaults to
 	\verb|"BH_diagnostics"|.
 
 \item[\code{BH\_diagnostics\_file\_name\_extension}]
+\mbox{}\\
 	This specifies the file name extension for black hole diagnostics
 	data files, as described above.  This defaults to \verb|"gp"|.
 \end{description}
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{(Excision) Mask Parameters}
+
+This thorn can optionally set a mask grid function at each point
+of the Cactus grid, to indicate where that point is with respect to
+the apparent horizon(s).  This is usually used for excision.
+This feature is controlled by the following parameteters:
+
+\begin{description}
+\item[\code{set\_horizon\_mask}]
+\mbox{}\\
+	If this Boolean parameter is set to true,
+	\thorn{AHFinderDirect} will set a mask grid function.
+	This parameter defaults to false (don't set a mask).
+
+\item[%%%
+     \begin{tabular}{@{}l@{}}
+     \code{mask\_radius\_multiplier[}$n$\code{]}	\\
+     \code{mask\_radius\_offset[}$n$\code{]}		%%%\\
+     \end{tabular}
+     ]
+\mbox{}\\
+	If we set a mask, we do so based on a \defn{mask volume}
+	for each horizon.  This is defined by
+	\begin{equation}
+	r(\rho,\sigma) = \verb|mask_radius_multiplier| \times h(\rho,\sigma)
+			 \,\,+\,\, \verb|mask_radius_offset| \times \Delta x
+	\end{equation}
+	where $(\rho,\sigma)$ are generic angular coordinates
+	on the horizon surface, $h(\rho,\sigma)$ gives the horizon
+	radius, $\Delta x$ is the Cactus grid spacing%%%
+\footnote{%%%
+	 More precisely, $\Delta x$ is the geometric mean
+	 of the $x$, $y$, and $z$ Cactus grid spacings.%%%
+	 }%%%
+,	and $r(\rho,\sigma)$ gives the radius of the mask volume.
+	The default values are $\verb|mask_radius_multiplier| = 0.9$
+	and $\verb|mask_radius_offset| = -5.0$ for each $n$,
+	giving a ``buffer zone'' (between the mask volume and
+	the horizon) of 20\% of the horizon radius, plus an extra
+	5~Cactus grid spacings.
+
+\item[\code{mask\_type}]
+\mbox{}\\
+	\thorn{AHFinderDirect} supports two types of mask grid functions;
+	this parameter chooses between them:
+	\begin{description}
+	\item[\code{"old-style (CCTK\_REAL)"}]
+	\mbox{}\\
+		This specifies an old-style excision mask, where a
+		\verb|CCTK_REAL| Cactus grid function is set to one
+		value inside the mask volume, and another value outside.
+		(This is how the \thorn{AHFinder} apparent horizon finder
+		works.)
+	\item[\code{"new-style (CCTK\_INT)"}]
+	\mbox{}\\
+		This specifies a new-style excision mask, where a
+		specified bit field in a \verb|CCTK_INT| Cactus
+		grid function is set to one value inside the mask
+		volume, and another value outside.  The bit field
+		is specified by its name, as registered with the
+		\thorn{SpaceMask} thorn.  We plan to convert all
+		Cactus excision (and other uses of mask grid functions)
+		to this scheme, but at the moment not much code supports it.
+	\end{description}
+
+\item[%%%
+     \begin{tabular}{@{}l@{}}
+     \code{old\_style\_mask\_gridfn\_name}	\\
+     \code{old\_style\_mask\_inside\_value}	\\
+     \code{old\_style\_mask\_outside\_value}	%%%\\
+     \end{tabular}
+     ]
+\mbox{}\\
+	If \verb|mask_type| is set to \verb|"old-style (CCTK_REAL)"|,
+	these parameters specify the mask grid function's name and
+	the (\verb|CCTK_REAL|) ``inside'' and ``outside'' values
+	respectively.
+
+\item[%%%
+     \begin{tabular}{@{}l@{}}
+     \code{new\_style\_mask\_gridfn\_name}		\\
+     \code{new\_style\_mask\_inside\_state\_name}	\\
+     \code{new\_style\_mask\_outside\_state\_name}	%%%\\
+     \end{tabular}
+     ]
+\mbox{}\\
+	If \verb|mask_type| is set to \verb|"new-style (CCTK_INT)"|,
+	these parameters specify the mask grid function's name,
+	and the ``state'' names for ``inside'' and ``outside'' values
+	as registered with the \thorn{SpaceMask} thorn.
+\end{description}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Accuracy}