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

1 files changed, 94 insertions, 25 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