better document new environment variables and build procedure;

move compiler portability notes from documentation.tex to top-level
README file


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

2 files changed, 166 insertions, 102 deletions

diff --git a/README b/README
index a057383..b105932 100644
--- a/README
+++ b/README
@@ -8,10 +8,10 @@ Purpose of the thorn
 ====================
 
 This thorn finds an apparent horizon given the 3D xyz-grid metric and
-extrinsic curvature.  It uses a direct method, writing the apparent
-horizon equation as an elliptic PDE on angular-coordinate space.  This
-is fast, but does require an intitial guess for the apparent horizon
-position.
+extrinsic curvature (and optionally the StaticConformal conformal factor).
+It uses a direct method, writing the apparent horizon equation as an
+elliptic PDE on angular-coordinate space.  This is fast, but does
+require an intitial guess for the apparent horizon position.
 
 
 Documentation
@@ -22,12 +22,6 @@ There are also a lot of comments in the param.ccl file on how to set
 the (many) parameters.
 
 
-Distribution
-============
-
-This thorn should eventually become part of the CactusEinstein arrangement.
-
-
 Copyright
 =========
 
@@ -52,18 +46,93 @@ Place, Suite 330, Boston, MA  02111-1307  USA
 Other Software Required
 =======================
 
-* This thorn requires the Einstein thorn.  (More accurately, it requires
-  various grid functions which are computed by the Einstein thorn.)
-* This thorn uses the new CCTK_InterpLocalUniform() interpolator API, which
-  at present is only supplied by the CactusBase/InterpLocal thorn.
-* This thorn is written in C++, so you'll need a C++ compiler to compile
-  this thorn.  (See the thorn guide for details.)  It calls the LAPACK
-  library (which in turn calls the BLAS library) for solving linear equations.
-  Before compilation you have to set the environment variable LAPACK_DIR
-  to give the directory in which to find the LAPACK and BLAS libraries.
-  On the AEI xeons this is
-     export LAPACK_DIR=/usr/bin			# bash
-     setenv LAPACK_DIR /usr/bin			# csh,tcsh
-* Most of this thorn's relativity code is machine-generated using Maple
-  (version 7), but you don't need Maple unless you want to modify the
-  relativity code.
+This thorn inherits from ADMBase and StaticConformal (both in the
+CactusEinstein arrangement), since it uses Cactus various grid functions
+which are defined in those thorns.
+
+This thorn uses the new CCTK_InterpLocalUniform() interpolator API, which
+at present is only supplied by the CactusBase/InterpLocal thorn.
+
+This thorn is written in C++, so you'll need a C++ compiler -- in fact
+a fairly modern one -- to compile this thorn.  See the "Compilation Notes"
+section below for details.
+
+Most of this thorn's relativity code is machine-generated using Maple
+(version 7), but you don't need Maple unless you want to modify the
+relativity code.
+
+This thorn uses the LAPACK library (which in turn uses the BLAS library).
+If you don't have these installed on your system already, you can get
+Fortran 77 source code and/or binaries for various architectures, from
+http://www.netlib.org/lapack/ and http://www.netlib.org/blas/ respectively.
+But many systems have these installed already -- try 'locate liblapack'
+and 'locate libblas' on your system.
+
+
+Library Configuration
+=====================
+
+Before compiling (a Cactus configuration which includes) AHFinderDirect,
+you must set the environment variable
+  LAPACK_DIR = a directory (or blank-separated list of directories)
+               containing the LAPACK and BLAS libraries.  (On GNU/Linux
+               systems this is usually /usr/lib or /usr/local/lib.)
+
+If the LAPACK and/or BLAS libraries were compiled with a (Fortran)
+compiler which is *not* used to compile any part of this Cactus'
+configuration, then you may also need to set the environment variables
+  LAPACK_EXTRA_LIBS = the name (or blank-separated list of names) of
+                      that (Fortran) compiler's run-time support
+                      library(ies)
+  LAPACK_EXTRA_LIBDIRS = the directory (or blank-separated list of
+                         directories) containing that library(ies)
+For example, if your LAPACK and/or BLAS were compiled with the GNU g77
+compiler (as is common on GNU/Linux and *BSD systems), and you are *not*
+using g77 to compile any part of your Cactus configuration, then you may
+need to set the environment variables to point to the g77 support library
+g2c:
+  LAPACK_EXTRA_LIBS = g2c
+  LAPACK_EXTRA_LIBDIRS = `g77 --print-file-name=libg2c.a | xargs basename`
+
+Note that all of these settings are of shell environment variables,
+using the syntax (eg)
+  $ export LAPACK_DIR=/usr/bin			# bash
+  % setenv LAPACK_DIR /usr/bin			# csh,tcsh
+Alas, setting these in your ~/.cactus/config file doesn't work. :(
+
+
+Code Notes
+==========
+
+This thorn is written in C++, and requires a fairly modern C++ compiler.
+In particular:
+* Templates are used, but only rather simple ones for containers or other
+  low-level stuff templated on the floating-point or integer datatype.
+  These templates are always instantiated explicitly.
+* bool, mutable, typename are used.
+* The new-style casts static_cast<...> and const_cast<...> are used.
+* The code will compile ok under either the archaic or the modern
+  for-loop declaration scope rules.
+* C header files are used in the pre-namespaces form (eg <stdio.h>).
+  (This is deprecated in standard \Cplusplus{}, but alas none of the
+  more modern forms (<cstdio> and namespace std::) seem to be supported
+  on as wide a range of systems as the pre-namespaces forms.
+* vector is the only part of the C++ standard template library (STL)
+  used, and for the same reasons as above.  Either <vector> or <vector.h>
+  may be used, depending on which of them exists (this is probed by the
+  Cactus configuration process).
+
+
+Compiler Notes
+==============
+
+The code has been compiled and run successfully using
+* gcc version 2.95.3 20010125 (prerelease)
+* gcc version 2.96 20000731 (Red Hat Linux 7.1 2.96-98)
+* g++ (GCC) 3.2
+* Intel(R) C++ Compiler for 32-bit applications, Version 5.0.1   Build 010730D0
+
+The code will almost certainly *not* compile using
+* any "egcs" version of gcc, or more generally, and version of gcc
+  earlier than 2.95
+* any version of Microsoft Visual C++ up to and including mid-2002
diff --git a/doc/documentation.tex b/doc/documentation.tex
index 9386009..94c56cd 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -201,7 +201,8 @@ We then write~\eqref{AEIDevelopment_AHFinderDirect_eqn-horizon} as a
 2-D elliptic PDE on $S^2$ for the function $h$.  We 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 Newton's method (or a variant with improved convergence).
+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
 singularities.  In general there are 6~patches, one each covering a
@@ -233,8 +234,8 @@ Computationally, this algorithm has 3 main parts:
 	so this computation is quite fast.  The Jacobian is a highly
 	sparse matrix, but at the moment we neglect this and store it
 	as a full (dense) matrix.  (This should change soon.)
-\item	Solving the nonlinear equations $H(h) = 0$ by Newton's method
-	or a variant.  At the moment this thorn uses a simple
+\item	Solving the nonlinear equations $H(h) = 0$ by a global Newton's
+	method or a variant.  At the moment this thorn uses a simple
 	Newton's-method solver, and solves the linear system using
 	$\sf LU$ decomposition routines from LAPACK
 	(this should change to a sparse $\sf LU$ decomposition/solution
@@ -256,69 +257,16 @@ 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
-lots of portability problems with various compilers having trouble
-with various features.%%%
-\footnote{%%%
-	 Not to mention various cases where I mistakenly
-	 wrote non-standard code, and my main development
-	 compiler (gcc) was ``tolerant'' and failed to warn
-	 me.  I consider any (such) occurence of code in
-	 \thorn{AHFinderDirect} which is illegal according
-	 to the \Cplusplus{} standard, to be a bug in
-	 \thorn{AHFinderDirect}, and will attempt to fix
-	 any such bugs.
-	 }%%%
-{}  As to specific \Cplusplus{} features\dots
-\begin{itemize}
-\item	Templates are used, but only rather simple ones for containers
-	or other low-level stuff templated on the floating-point or
-	integer datatype, and these templates are always instantiated
-	explicitly.
-\item	\code{bool}, \code{mutable}, and \code{typename} are used.
-\item	New-style casts are used, \eg{}
-	\begin{verbatim}
-	const CCTK_REAL* const_real_ptr(const void* vp)
-	{
-	return const_cast<const CCTK_REAL*>(vp);
-	}
-	\end{verbatim}
-\item	The code will work ok under either the archaic or the modern
-	\code{for}-loop declaration scope rules.
-\item	C header files are used in the pre-namespaces form
-	\begin{verbatim}
-	#include <stdio.h>
-	int main()
-	{
-	printf("hello, world\n");
-	return 0;
-	}
-	\end{verbatim}
-	This is deprecated in standard \Cplusplus{}, but alas
-	none of the more modern forms using the \code{std::} namespace
-	seem to be supported on as wide a range of systems as the
-	pre-namespaces forms.
-\item	\code{vector} is the only part of the C++ standard template library
-	(STL) used, and for the same reasons as above, it's used in the
-	pre-namespaces \verb|<vector.h>| form.
-\end{itemize}
-
-The code has been compiled and run successfully using
-\begin{itemize}
-\item	various {\bf gcc} versions (2.95.2, 2.95.3, and 3.2) versions
-	on x86 GNU/Linux and *BSD (these are my main development compilers)
-\end{itemize}
-
-Right now there are (still) problems with
-\begin{itemize}
-\item	Intel C++ compiler for GNU/Linux, version 5.0.1 and 6.0
-\end{itemize}
-(I consider these bugs in \thorn{AHFinderDirect}, and am attempting
-to fix them.)
+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.
 
-The code will almost certainly {\em not\/} compile using either
-ancient compilers like any {\bf egcs} gcc version, or with badly broken
-compilers like any version of Microsoft Visual \Cplusplus{} up to and
-including those of mid-2002 (I don't know about newer versions).
+To compile (a Cactus configuration which includes) this thorn, you
+must set the environment variable \code{LAPACK\_DIR}, and possibly
+also the environment variables \code{LAPACK\_EXTRA\_LIBS} and
+\code{LAPACK\_EXTRA\_LIBDIRS}.  See the ``Library Configuration''
+section in the top-level \code{README} file for details.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -329,8 +277,12 @@ 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):
 \begin{description}
-\item[\code{find\_AHs\_at\_postinitial},
-      \code{find\_AHs\_at\_poststep}]
+\item[%%%
+      \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)?
 \item[\code{N\_horizons}]
@@ -353,16 +305,59 @@ probably need to set the following parameters explicitly
 	 time we try to find this same apparent horizon.
 	 }%%%
 {}	This can either be read from an input file or files, set to
-	a specified coordinate sphere or ellipsoid, or set to the
-	(analytical) event horizon of a Kerr spacetime in either
-	Kerr or Kerr-Schild coordinates.  For the sphere, ellipsoid,
-	and Kerr options there are additional parameters to specify
-	the center position, radius or radia, and if appropriate
-	the Kerr mass and spin.
-
-	All of these latter parameters are Cactus array parameters,
-	\ie{} you need to specify them separately in your parameter
-	file for each apparent horizon you're searching for.
+	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"|.
+\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