Make "Erik" branch the default trunk for AHFinderDirect.

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

3 files changed, 119 insertions, 22 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..dadc3b5
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,61 @@
+# Makefile for documentation
+# $Header: /usr/local/svn/cvs-repositories/numrelcvs/AEIThorns/AHFinderDirect/doc/Makefile,v 1.7 2003-07-31 17:30:20 jthorn Exp $
+
+#
+# ***** main targets *****
+# default	latex & dvips everything
+# bib		bibtex everything
+# clean		remove all machine-generated files
+#
+# ***** targets for rebuilding figures in the thorn guide *****
+# 3patch-cactus		run Cactus to generate the data file for the
+#			3patch figure
+# 3patch-gnuplot	run gnuplot to generate the postscript file
+#			for the 3patch figure
+#
+
+#
+# Note this Makefile always re-TeXs things, even if the .tex files
+# haven't changed (and similarly for dvips); this ensures that changes
+# to macros, included stuff from other directories, etc, get "used".
+# To implement this, we declare the .dvi and .ps files as "PHONY".
+#
+
+###############################################################################
+
+#
+# ***** main targets *****
+#
+
+.PHONY	: default
+default	: ps
+
+.PHONY	: ps
+ps	: dvi
+	dvips -f <documentation.dvi >documentation.ps
+
+.PHONY	: dvi
+dvi	:
+	latex documentation
+
+.PHONY	: bib
+bib	:
+	bibtex documentation
+
+.PHONY	: clean
+clean	:
+	-rm *.dvi *.ps *.aux *.bbl *.log *.blg
+
+###############################################################################
+
+#
+# ***** targets for rebuilding figures in the thorn guide *****
+#
+
+.PHONY		: 3patch-cactus
+3patch-cactus	:
+	cactus_test-ahfinderdirect 3patch.par 2>&1 | tee 3patch.log
+
+.PHONY		: 3patch-gnuplot
+3patch-gnuplot	:
+	gnuplot 3patch.gnuplot
diff --git a/doc/TODO b/doc/TODO
index feb4cc4..1b9941e 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -1,16 +1,10 @@
 small things
-  if the user asks for a mask to be set, and we find a horizon,
-    but the mask parameters are such that we don't mask any grid points,
-    then we should give a warning that something may be wrong...
-  many more parameters should be steerable
-    (find_every would be easy and already useful)
-  document what parameters would be needed if ghost_size is restricted to 1
   give a cogent error message (instead of core-dumping like we do right now)
     if we try to set a mask and nobody's registered the bitfield yet
   add a "find_after" or "find_when" option so we can specify the times at
     which we want to find a given horizon(s)
-  have some way to make  find_every  specifyable on a per-horizon basis
-    (maybe with two parameters like we do for whether or not to set the mask)
+  add an option to compute/output the surface radius on a latitude/longitude
+    grid
   I should set CXXFLAGS for this thorn to turn off automagic template
     instantiation on those platforms (eg lemieux, modi4) where it's on
     by default (Thomas Radke says to copy FlexIO's scheme for doing this)
@@ -23,13 +17,6 @@ small things
   implement a log file where the full "algorithm highlights" (or whatever)
     messages can go even if stdout (= the Cactus run's log file) only gets
     less-verbose messages
-  output all surfaces with the same "parity", eg rho x sigma should point out
-    or suchlike
-  Sascha Husa & Sergio Dain would like the ability to search for
-    "antitrapped surfaces", i.e. to flip the sign of $K_{ij}$
-    (Bernd Reimann is also interested in this)
-  allow absolute paths in file names (eg for BH diagnostics file)
-    to override IO::out_dir or AHFinderDirect::h_dir
 
 medium things
   switch to UMFPACK 4.1 and ATLAS BLAS, cf
@@ -43,9 +30,8 @@ medium things
     if there exists a point which was excised at the last time step,
        and which this AH would not excise,
     then skip all excision for this AH
+  properly interface to Erik's SphericalSurface thorn
   compute Gaussian curvature, cf AHFinder/src/AHFinder_gau.F
-  HDF5 data files (simple format and/or Werner Benger's fancy one)
-  move origin point to track moving BHs
   read AHFinder Fourier coeffs for initial guess
   write data files giving intersection of AH with a Cactus output plane
      (or more generally, with a hyperslab)
diff --git a/doc/documentation.tex b/doc/documentation.tex
index 95e145d..e2116cb 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -1298,20 +1298,32 @@ This is controlled by the following parameters:
 \begin{description}
 \item[%%%
      \begin{tabular}{@{}l@{}}
-     \code{run\_at\_CCTK\_ANALYSIS}	\\
-     \code{run\_at\_CCTK\_POSTSTEP}	\\
-     \code{run\_at\_CCTK\_POSTINITIAL}	%%%\\
+     \code{run\_at\_CCTK\_ANALYSIS}			\\
+     \code{run\_at\_CCTK\_POSTSTEP}			\\
+     \code{run\_at\_CCTK\_POSTINITIAL}			\\
+     \code{run\_at\_CCTK\_POST\_RECOVER\_VARIABLES}	%%%\\
      \end{tabular}
      ]
 \mbox{}\\
 	These parameters (which default to \verb|true|, \verb|false|,
-	and \verb|false| respectively) control which schedule bins
-	\thorn{AHFinderDirect} runs in.  Historically,
+	\verb|false|, and \verb|true| respectively) control which
+	schedule bins \thorn{AHFinderDirect} runs in.  Historically,
 	\thorn{AHFinderDirect} ran in CCTK\_ANALYSIS, and that's
 	still the default, but these parameters allow you to change this
 	so it runs in CCTK\_POSTSTEP and/or CCTK\_POSTINITIAL
 	instead.  (You can even run in all three bins if you want!)
 
+	In general we need to run at CCTK\_POST\_RECOVER\_VARIABLES, since
+	\begin{itemize}
+	\item	parameters may have been steered at recovery, so we may need
+		to find a new horizon or horizons, and
+	\item	we need to set the mask again to make sure it's correct
+		right away (since our next regular horizon-finding may not
+		be until some time steps later)
+	\end{itemize}
+	Therefore the \verb|run_at_CCTK_POST_RECOVER_VARIABLES| parameter
+	should probably be left at its default setting of \verb|true|.
+
 \item[%%%
      \begin{tabular}{@{}l@{}}
      \code{geometry\_interpolator\_name}	\\
@@ -1651,6 +1663,44 @@ AHFinderDirect::initial_guess__coord_sphere__radius[1] = 2.0
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+\section{Surfaces of Constant Expansion}
+
+Surfaces of Constant Expansion (CE surfaces) are introduced in
+\cite{AHFinderDirect/Schnetter03a} as a generalisation of
+apparent horizons (AH).  On an AH surface, the expansion is zero
+everywhere.  On a CE surfaces, the expansion is still everywhere the
+same, but it need not be zero.  CE surfaces are also a generalisation
+of Constant Mean Curvature surfaces (CMC surfaces); both are identical
+when the extrinsic curvature vanishes.  As described in
+\cite{AHFinderDirect/Schnetter03a}, it is likely that CE
+surfaces foliate the spacelike hypersurface outside of some interior
+region.  This interior region is inside the common apparent horizon,
+if it exists.
+
+CE surfaces can give some insight into the spacetime, because they can
+be used to analyse the part of the spacelike hypersurface ``between
+the horizons and infinity''.  Most notably, they can be used to look
+at the region where a common horizon is about to (or believed to)
+form.  Similarly, one can use them for collapsing stars where an
+apparent horizon has not yet formed.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Pretracking}
+
+Apparent horizon pretracking is introduced in
+\cite{AHFinderDirect/Schnetter03a}.  This is an application
+of CE surfaces.  Even when there is no common horizon, there are still
+common CE surfaces surrounding multiple black holes.  Pretracking
+consists of tracking in time the smallest common CE surface that can
+be found.  It is reasonable to believe that this surface will evolve
+into the common horizon at the time where this common horizon begins
+to exist.  The expansion of this smallest CE surface is also an
+indication of how close the spacelike hypersurface is to having a
+common apparent horizon.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \section{How \thorn{AHFinderDirect} Works}
 \label{AHFinderDirect/sect-how-ahfinderdirect-works}