Added description of how to get Carpet, and where to find simple

Added description of how to get Carpet, and where to find simple
example parameter files.

darcs-hash:20021129154835-07bb3-37272c5bc900fe3149449af95b894ee77855c5d2.gz

1 files changed, 165 insertions, 17 deletions

diff --git a/Carpet/doc/documentation.tex b/Carpet/doc/documentation.tex
index 0265a7ac2..73714b450 100644
--- a/Carpet/doc/documentation.tex
+++ b/Carpet/doc/documentation.tex
@@ -2,7 +2,7 @@
 %  Cactus Thorn template for ThornGuide documentation
 %  Author: Ian Kelley
 %  Date: Sun Jun 02, 2002
-%  $Header: /home/eschnett/C/carpet/Carpet/Carpet/doc/documentation.tex,v 1.2 2002/11/29 10:43:43 schnetter Exp $                                                             
+%  $Header: /home/eschnett/C/carpet/Carpet/Carpet/doc/documentation.tex,v 1.3 2002/11/29 16:48:35 schnetter Exp $                                                             
 %
 %  Thorn documentation in the latex file doc/documentation.tex 
 %  will be included in ThornGuides built with the Cactus make system.
@@ -64,7 +64,7 @@
 % *======================================================================* 
 
 % If you are using CVS use this line to give version information
-% $Header: /home/eschnett/C/carpet/Carpet/Carpet/doc/documentation.tex,v 1.2 2002/11/29 10:43:43 schnetter Exp $
+% $Header: /home/eschnett/C/carpet/Carpet/Carpet/doc/documentation.tex,v 1.3 2002/11/29 16:48:35 schnetter Exp $
 
 \documentclass{article}
 
@@ -85,7 +85,7 @@
 
 % the date your document was last changed, if your document is in CVS, 
 % please use:
-\date{$ $Date: 2002/11/29 10:43:43 $ $}
+\date{$ $Date: 2002/11/29 16:48:35 $ $}
 
 \maketitle
 
@@ -290,34 +290,182 @@ usable.  You will have to install a complete copy of FlexIO by hand.
 
 \subsection{Hurdle 1: FlexIO}
 
-DESCRIBE INSTALLING FLEXIO HERE.  MENTION INSTALLING HDF4 FIRST, THEN
-HDF5, THEN FLEXIO.
+I suggest that you enable support for the HDF format in the FlexIO
+library, although this is not necessary.  If you don't want to do
+this, then you don't have to install the HDF libraries in the
+following.
+
+\begin{enumerate}
+
+\item
+Install the HDF4 and HDF5 libraries.  They are available from the HDF
+web pages \cite{Carpet__HDF}, and they can be installed with the usual
+\texttt{./configure; make; make install} triplet.  They should already
+be installed by default on most machines.  The conversion utilities
+between HDF4 and HDF5 are installed automatically when you install
+HDF5 while HDF4 is already installed.  (That means that you should
+install HDF4 first, and then HDF5.)
+
+\item
+Get the FlexIO library from the Cactus CVS server:\\ \texttt{cvs -d
+:pserver:\textit{yourlogin}@cvs.cactuscode.org:/packages checkout
+FlexIO}.  If you do not have a login, then use the login
+\texttt{cvs\_anon} for anonymous access.  The Cactus web pages
+describe how to do this.
+
+\item
+Configure FlexIO while providing the paths to the HDF4 and HDF5
+libraries: \texttt{./configure --with-hdf4=/usr --with-hdf5=/usr},
+assuming that HDF4 and HDF5 are installed under \texttt{/usr}.  You
+can also configure without HDF support, but then you will not be able
+to read or write HDF files.  FlexIO will then support only the
+built-in \texttt{IEEEIO} format.
+
+\item
+Edit the top of the file \texttt{FlexIO/Makefile} to match your actual
+configuration.  The \texttt{./configure} script of FlexIO is a bit
+simplistic, so don't spend too much effort trying to convince it to do
+the right thing.
+
+On my machine, I had to change the settings \texttt{CC = mpicc},
+\texttt{C++ = mpiCC -DMPICH\_SKIP\_MPICXX}, and \texttt{HDFINCLUDES =
+-I\$(HDFROOT)/include/hdf} by hand.  I am using Debian Linux on an
+IA32 with gcc 2.95.4 and MPICH 1.2.4, and I have an HDF5 library where
+support for parallel I/O was enabled.
+
+\item
+Compile the library with \texttt{make}.
+
+\item
+The library cannot be installed automatically.  You usually use the
+include and library files where they are.  If you want to install the
+library, copy all the header files (\texttt{*.h *.hh *.H}) and the
+library files (\texttt{*.a}).
+
+\end{enumerate}
+
+Yes, I also think that this is way too complicated.
 
 \subsection{Hurdle 2: STL}
 
-DESCRIBE HOW TO GET/INSTALL AN STL, OR HOW TO MAKE THE SYSTEM'S C++
-COMPILER WORK WITH THE STL.
+Some operating systems do not have a compliant STL (Standard Template
+Library) installed.  If not, then you are in trouble.  Carpet does
+make use of the STL, and there is no way around that.
 
 \subsection{Hurdle 3: Templates}
 
-DESCRIBE HOW TO INSTANTIATE, AND NOT-INSTANTIATE, THE TEMPLATES AS
-NEEDED.
+Some compilers contain switches to instantiate some or all templates
+automatically.  This usually does not work when files are put into
+libraries, which is what Cactus does.  The scheme that I found working
+on all machines is to instantiate most templates by hand, and have the
+compiler instantiate the missing templates for every object file.
+This is the default for gcc.  On SGIs, you have to pass the options
+\texttt{-no\_auto\_include -ptused} to the C++ compiler.
 
-\subsection{WaveToy}
+The C++ standard specifies a limit when using templates as template
+parameters.  Carpet's use of the GNU STL exceeds this limit.  Gcc
+requires the option \texttt{-ftemplate-depth-30} to enable this.
 
-CONFIGURING, THORNS, COMPILING.
+\subsection{WaveToy}
 
-To be continued\ldots
+Unfortunately, PUGH and Carpet cannot yet be both compiled into a
+single application.  (This will be fixed soon.)  That means that you
+will have separate executables for unigrid and for mesh refinement
+applications.
+
+Configuring Carpet is not quite trivial, because Cactus provides
+currently no way to autodetect the settings for Carpet.  Hence you
+will have to set the settings manually.  I propose that you start with
+on of the pre-made options files in the directory
+\texttt{Carpet/Carpet/options}.  Try e.g.\ \texttt{carpet-harpo-sgi}
+for an SGI, or \texttt{carpet-lilypond} for Linux with gcc, or
+\texttt{carpet-lilypond-ic} for Linux with the Intel compilers.  Once
+you have a working options file for your machine, send it to me, so
+that I can include it.
+
+As for the thorn list: Carpet has its own ASCII output thorn, which
+outputs more information than CactusBase/IOASCII.  The thorn list that
+I use is
+
+\begin{verbatim}
+CactusBase/Boundary                # boundary (grid) [ ] { }
+CactusBase/CartGrid3D              # grid ( ) [ ] {driver}
+#CactusBase/IOASCII                 # IOASCII (IO,Hyperslab) [ ] {IO}
+CactusBase/IOBasic                 # IOBasic (IO) [ ] {IO}
+CactusBase/IOUtil                  # IO ( ) [ ] { }
+CactusBase/LocalInterp             # LocalInterp ( ) [ ] { }
+CactusBase/Time                    # time ( ) [ ] { }
+CactusConnect/HTTPD                # HTTPD (Socket) [ ] {Cactus}
+CactusConnect/HTTPDExtra           # http_utils (httpd,IO) [ ] { }
+CactusConnect/Socket               # Socket ( ) [ ] { }
+#CactusExternal/FlexIO              # FlexIO ( ) [ ] { }
+CactusExternal/jpeg6b              # jpeg6b ( ) [ ] { }
+CactusIO/IOJpeg                    # IOJpeg (IO,Hyperslab,jpeg6b) [ ] {IO}
+CactusUtils/NaNChecker             # NaNChecker ( ) [ ] { }
+CactusWave/IDScalarWave            # idscalarwave (wavetoy,grid) [ ] {grid}
+CactusWave/IDScalarWaveC           # idscalarwave (wavetoy,grid) [ ] {grid}
+CactusWave/IDScalarWaveCXX         # idscalarwave (wavetoy,grid) [ ] {grid}
+#CactusWave/IDScalarWaveElliptic    # idscalarwaveelliptic (grid,wavetoy,ellbase) [ ] {idscalarwave}
+CactusWave/WaveBinarySource        # binarysource (wavetoy,grid,idscalarwave) [ ] { }
+CactusWave/WaveToyC                # wavetoy (Grid,Boundary) [ ] { }
+CactusWave/WaveToyCXX              # wavetoy (Grid,Boundary) [ ] { }
+CactusWave/WaveToyF77              # wavetoy (Grid,Boundary) [ ] { }
+#CactusWave/WaveToyF90              # wavetoy (Grid,Boundary) [ ] { }
+#CactusWave/WaveToyFreeF90          # wavetoy (Grid,Boundary) [ ] { }
+Carpet/Carpet                      # driver (CarpetLib) [ ] {Cactus,IO}
+Carpet/CarpetIOASCII               # IOASCII (CarpetLib,driver,Hyperslab) [ ] {IO}
+Carpet/CarpetIOFlexIO              # IOFlexIO (CarpetLib,driver,Hyperslab) [ ] {IO}
+#Carpet/CarpetIOHDF5                # IOHDF5 (CarpetLib,driver,Hyperslab) [ ] {IO}
+#Carpet/CarpetIOSer                 # IOSer (CarpetLib,driver,Hyperslab) [ ] {IO}
+Carpet/CarpetLib                   # CarpetLib ( ) [ ] { }
+Carpet/CarpetReduce                # reduce (CarpetLib,driver) [ ] { }
+Carpet/CarpetRegrid                # CarpetRegrid (CarpetLib,driver) [ ] { }
+Carpet/CarpetSlab                  # Hyperslab (CarpetLib,driver) [ ] { }
+\end{verbatim}
+
+The thorns prefixed with \texttt{\#} are disabled.  IOASCII conflicts
+with CarpetIOASCII, and FlexIO conflicts with the external FlexIO
+library that CarpetIOFlexIO uses.  I disabled IDScalarWaveElliptic
+because there is no elliptic solver for mesh refinement, and I
+disabled WaveToyF90 and WaveToyFreeF90 because gcc does not contain a
+Fortran 90 compiler.  CarpetIOHDF5 is not yet finished, and
+CarpetIOSer needs the Ser library which is not publically available.
+
+The CactusConnect, CactusExternal, CactusIO, and CactusUtils thorns
+are not necessary, but are nice to have around.  You can safely omit
+these.
 
 
 
 \section{Running The Example Applications}
 
-SAMPLE FILES
-
-CARPET'S OPTIONS
-
-To be continued\ldots
+Although Carpet works fine with the standard WaveToy thorns, all the
+example parameter files in the CactusWave arrangement use PUGH, and
+can therefore not be directly used.
+
+The coordinate thorn CactusBase/CartGrid3D does not provide periodic
+boundary conditions.  These are normally provided by the driver PUGH.
+However, Carpet does not contain any boundary conditions.  If you want
+to apply periodic boundaries, you will therefore have to use the
+AlphaThorns/Cart3d coordinate thorn instead, which does provide
+periodicity.  Unfortunately, AlphaThorns/Cart3d is incompatible with
+CactusBase/CartGrid3D.  There is a version of WaveToy in the Carpet
+arrangement that has been adapted to AlphaThorns/Cart3d.  I suggest
+that you use this version of WaveToy instead of CactusWave to run test
+problems, because periodicity makes for nice testing setups.
+
+You can find quite a few example parameter files in the directory
+\texttt{Carpet/WaveToyF77/par}.  I especially recommend the
+\texttt{wavetoyf77\_periodic\_*} set, which comes in two sizes
+(\texttt{coarse} and \texttt{fine}, corresponding to a small and a
+large simulation domain) and three different refinement hierarchies
+(with one, two, and three level altogether, respectively).  This set
+thus forms a convergence test, which you can run and test yourself.
+The set \texttt{wavetoyf77\_rad\_full\_*} uses radiative instead of
+periodic boundaries and should also be nice to look at.  The file
+\texttt{wavetoyf77\_rad\_automatic.par} is an attempt at adaptive mesh
+refinement, which may or may not work, depending on the current status
+of Carpet.
 
 Second order convergence requires second order interpolation in time,
 which requires that at least three time levels are present.