Renamed files so that we don't have to change numbers to add parts.

Started adding functions to the Infrastructure part.


git-svn-id: http://svn.cactuscode.org/flesh/trunk@237 17b73243-c579-4c4c-a9d2-2d5706c11dac

1 files changed, 635 insertions, 0 deletions

diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex
new file mode 100644
index 00000000..9434963b
--- /dev/null
+++ b/doc/UsersGuide/RunningCactus.tex
@@ -0,0 +1,635 @@
+\part{Introduction}
+
+\chapter{Overview of documentation}
+
+This documentation splits naturally into these parts: 
+
+\begin{itemize}
+
+\item {\bf The history of Cactus and the Concepts behind the
+    CCTK. Getting you up and running.}
+  We give an overview on the required hardware and
+  software and we will talk you through the installation of a working
+  CCTK. You will be able to verify the correct installation by the
+  CCTK test suite. We show how to perform some basic simulation and
+  introduce the concepts behind data output. We provide brief
+  information on how to visualize the 1D, 2D and 3D data.
+
+\item {\bf Part2: How to write a physics thorn.} We introduce a
+  sample thorn that illustrates the implementation of simple initial
+  data and the subsequent evolution. You will learn how to use the
+  programming interface to take advantage of parallelism and modularity.
+
+\item {\bf Part3: How to writes an infrastructure thorn.} In this more
+  advanced part, we talk about user supplied infrastructure routines
+  as {\em additional output routines, boundary conditions, etc.}
+
+\item {\bf The standard toolkit.} 
+
+\end{itemize}
+
+Other topics will be discussed in separate documents:
+
+\begin{itemize}
+
+\item The numerical relativity toolkit.
+
+\item A description of the flesh, for the maintainers.
+
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{A Cactus history}
+
+To begin with a one-phrase summary: Cactus is a numerical
+infrastructure for solving partial differential equations (typically
+in 3-dimensional space and time), a modular code for solving the
+Einstein equations, and an international collaboration in numerical
+general relativity pooling ideas in this code.
+
+Cactus 1.0 was written in 1996 by Joan Mass\'o and Paul Walker out of
+frustration with the numerical relativity codes they had been working
+on. It has come a long way. The name is meant to suggest a modular
+structure consisting of a ``flesh'' (or backbone, or core) and
+``thorns'' (or modules, or collections of subroutines). Some essential
+features of the code have been present from the beginning:
+
+\begin{itemize}
+
+\item Parallelism (the work is split between multiple processors, or
+multiple computers) that is largely automatic and hidden from the
+user.
+
+\item A modular structure with a fixed interface between the flesh and the
+thorns, which allows users to add new parts.
+
+\item Giving the user a choice of C and Fortran for writing thorns, while
+automating the interface between the two languages.
+
+\item A spirit of open-source collaboration similar to the gnu
+project.
+
+\end{itemize}
+
+Other aspects have changed completely since Cactus 1.0. The flesh
+started out as a complete numerical relativity code, using one
+particular formulation of the Einstein equations, with the thorns
+providing only initial data, analysis, and other peripheral
+functions. In 4.0 not only the Einstein equations and general
+relativity basics, but even input/output and parallelism are provided
+by thorns. The only function of the flesh is now to define the
+interface between thorns, to hold varying collections of thorns, and
+to provide an interface between C and Fortran routines. 
+
+The aim of this radicalism is to allow for future growth. We now
+distinguish informally between physics thorns and infrastructure
+thorns. The main infrastructure project for now is adding different
+flavors of adaptive mesh refinement -- while the user writing a
+physics thorn can still large she is working a single-processor,
+unigrid code. Similarly, an infrastructure thorn could be replaced by
+one that does the same job, but simply better. Even the flesh could be
+rewritten in the future, but the interface between the flesh and
+thorns is to remain unchanged.
+
+Cactus thorns can be written in F90, F77 and C (or a mixture). The
+decision to support Fortran was made for the pragmatic reason that
+many people like it, or don't write C. This decision does make the
+flesh more complex. The flesh is written in C, and in perl that
+generates C.
+
+The change from Cactus 3.0 to Cactus 4.0 is the largest one yet. The
+new interface forces modifications on all existing thorns, but it is
+intended not to change again. {\q Can we realistically say any more?}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Cactus concepts} 
+
+Cactus is designed to solve time evolution problems in three space
+dimensions by finite differencing on a Cartesian grid. This typically
+includes solving elliptic equations to obtain initial data, evolving
+them by hyperbolic or parabolic equations, and perhaps solving more
+elliptic equations at each time step.  One basic concept is therefore
+a series of initialization steps followed by a do-loop that implements
+the time evolution, along with periodic analysis and output. Problems
+that do not naturally fit into this concept are methods which are
+global in space or time (such as pseudo-spectral methods) or methods
+which do not have a grid (such as finite elements). Thorns interact
+with the flesh by, among other things, announcing when they want to be
+called in this basic schedule.
+
+Another basic concept is parallelism by distributing spatial domains
+among processors. Finite differencing is an almost local procedure,
+which means that each processor can work on its domain of space,
+needing to communicate only with neighboring processors in order to
+work on points of the boundary of its domain. The domain decomposition
+is automatic and largely hidden. A physics thorn can pretend to work
+on a single grid, which in reality is only a chunk of the complete
+numerical domain. This chunk consists of an inner region of points the
+processor ``owns'', and needs to update, surrounded by a ``ghost
+zone'' of points which it can use but doesn't need to update -- they
+are updated by neighboring processors. Clearly this concept is geared
+towards explicit finite differencing schemes for the time-evolution
+part. {\q Say something about elliptic equations here, and implicit
+schemes}
+
+The notion that we are dealing with a collection of fields that live
+on the same (typically three-dimensional) space, and that evolve
+together in time defines the third basic concept, that of ``grid
+functions'' grouped together in a ``grid hierarchy''. Multiple
+grid hierarchies arise, for example, when one wants to cover the
+surface of a sphere with two Cartesian coordinate patches, or in
+adaptive mesh refinement.  Grid functions are defined on Cartesian
+grids that are equally spaced in each of the three coordinates $x$,
+$y$ and $z$. (These could be spherical type coordinates, although that
+was not the original intention.) Grid functions can be two or
+one-dimensional as well as three dimensional.
+
+Routines are grouped in thorns, and thorns informally in toolkits,
+such as the standard toolkit, and the general relativity
+toolkit. The routines inside a thorn can interact in any way, but
+thorns interact with the flesh and with each other only through a
+well-defined interface. Confirming to this interface guarantees that
+thorns will be compatible with, and useful for, all future extensions
+of the code. The interface also helps users and developers to
+understand what a given thorn does. 
+
+The flesh and many thorns are public and can be used by anyone,
+assuming ethical behavior. Public thorns and the flesh are distributed
+by CVS (see {\q where?} below). Public thorns are checked out in
+toolkits. The flesh may change in the future but this should never
+affect users, as Cactus 4.0 is making every effort to codify and
+freeze the interface. Public thorns should of course not lose
+important functionality they once had. (Nevertheless, CVS gives the
+user access to all earlier versions.)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Installation} 
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Required software}
+
+In general, Cactus {\em requires} the following set of software to function
+in a single processor mode. Please refer to the architecture section
+\ref{sec:architecture} for architecture specific items.
+\begin{itemize}
+\item{\tt Perl5.0} Perl is used extensively during the CCTK
+  configuration phase. Perl is available for nearly all
+  operating systems known to man and can be obtained at
+  http://www.perl.org
+\item{\tt gmake} The GNU make utility has to be installed. The make
+  process will not work with anything else the GNU.
+  Gmake can be obtained from your favorite GNU site.
+\item{\tt C/C++} A C/C++ compiler. These can be the GNU compilers as
+  well, but don't have to.
+\item{\tt CVS} The {\em ``Concurrent Versioning System''} is not needed
+  to run/compile the CCTK, but you are strongly encourage to install
+  this software to take advantage of the update procedures. It can be
+  downloaded from your favorite GNU site.
+\end{itemize}
+
+\noindent
+The following software is {\em optional} and not needed to get the
+basic CCTK installation on track. Its listed in the order of importance.
+\begin{itemize}
+\item{\tt Fortran 90} CCTK requires a F90 compiler to run modules
+  written in F77 or F90. There is no
+  GNU F90 and just a very limited set of free F90 compilers for
+  various architectures.
+\item{\tt MPI} Currently the communication layer of the CCTK uses the
+  {\em Message Passing Interface (MPI)} provide inter process
+  communication. Supercomputers very often supply a native MPI
+  implementation at their site. CCTK is very likely to work with
+  them. For local area networks we suggest installing the {\tt MPICH}
+  version, which can be obtained for various architectures and
+  operating systems at {\tt http://www-unix.mcs.anl.gov/mpi/}.
+\item{\tt TAGS}: Tags enables you browse through the calling structure
+  of a program by help of function call database. Navigating the CCTK and
+  Toolkits becomes very easy. Emacs and vi both support this database. See
+  \ref{sec:tags} how to install ``tags''.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Supported architectures}
+Cactus runs on many machines, under a large number of Unix operating
+systems. Here we list all the machines we have compiled and verified
+Cactus on, including some architecture specific notes. 
+\begin{itemize} 
+\item{\bf SGI Origin 2000}
+\item{\bf SGI}
+\item{\bf Cray T3E}
+\item{\bf Dec Alpha}: Dec operating system and Linux. Single processor
+  mode and MPICH.
+  supported. The Decs need to have the GNU {\tt C/C++} compilers installed.
+\item{\bf Intel Linux}: There is a
+  free Linux F90 compiler available from  {\tt http://www.sierra.com}
+  -- the only free we know of. Single processor mode and MPICH
+  supported.
+\item{\bf Windows32 using Cygwin32 extensions} {\q still true?}
+\item{\bf Windows NT}: successful compile with the following software:
+  \begin{itemize}
+  \item{\tt DIGITAL Visual Fortran Optimizing Compiler Version: V5.0C}
+  \item{\tt Microsoft (R) 32-bit C/C++ Optimizing Compiler Version
+        11.00.7022 for 80x86}
+  \item{Cygnus Unix suite version 1.19}
+  \end{itemize}
+\item{\bf Solaris } {\q What is the status on this ??}
+\end{itemize}
+If you did not find you architecture/operating system of
+choice, see section sec\ref{sec:how_to_port} on how to port to an
+unsupported architecture.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Checkout procedure}
+
+Cactus is distributed, added to, and updated through the free CVS
+software. CVS ({\em ``Concurrent Versioning System''}) allows many
+people to work on a large software project together without getting
+into a tangle by keeping track of changes made by the different
+users. For the beginner, we summarize the basics in appendix
+\ref{sec:CVS}, please refer to this section for small description of
+the CVS syntax.
+
+The installation requires about {\q HOW MANY MEGS ? }. See section
+\ref{sec:downsize_CCTK} on how to downsize CCTK installation if space is tight.
+{\q gmake small ??}
+
+\begin{itemize}
+\item{\bf Login}: Prior to any CVS operation, you need to log into the central
+  repository. For an anonymous checkout, type:\\
+  {\tt
+    cvs -d :pserver:cvs\_anon@hod.aei-potsdam.mpg.de:/usr/users/cactus login
+    }
+  You will be prompted for a password which is {\tt anon}. 
+\item{\bf Checkout}: To obtain a fresh CCTK checkout, type
+  {\t
+    cvs -d :pserver:cvs\_anon@hod.aei-potsdam.mpg.de:/usr/users/cactus checkout cactus
+    }
+  The CVS checkout procedure will create a directory called {\tt
+    ./CCTK} and install the CCTK inside this directory.  From now on we
+  will reference all directory names relative to {\tt ./CCTK}. 
+  
+\item{\bf Update}: To update an existing CCTK checkout (to patch in
+  possible changes, etc.), do the following {\em within} the {\tt ./CCTK} directory.
+  {\t
+    cvs -d :pserver:cvs\_anon@hod.aei-potsdam.mpg.de:/usr/users/cactus update
+    }
+  The update process will operate downwards relative to you current position
+  within the CCTK tree. To update only certain directories, change
+  into these directories and issue the update command.
+\item{\bf CVS status}: to obtain a status report on the ``age'' of your
+  CCTK or Toolkit routines (from your current directory position
+  downward), type
+  {\t
+    cvs -d :pserver:cvs\_anon@hod.aei-potsdam.mpg.de:/usr/users/cactus status
+    }
+\item{\bf non-anonymous CVS}: if you have an account at the central
+  repository and you would like to perform any of the operation above
+  {\em non-anonymously}, replace {\tt cvs\_anon} by your login name
+  and provide the appropriate password during the CVS login
+  process. Depending on your permissions, you may then make commits to the CCTK
+  or its Toolkits.
+\item{\bf Commits}: you need to perform a personalized login and have
+  proper permissions to commit code to the repository. 
+\end{itemize}
+For more CVS commands on how to add files, etc. please refer to appendix \ref{sec:CVS}.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Directory structure}
+
+A fresh CCTK checkout creates a directory {\tt ./CCTK} with the
+following files substructure:
+\begin{itemize}
+
+\item{\tt ./CVS/} the CVS book-keeping directory, present in every subdirectory.
+
+\item{\tt ./doc/} CCTK documentation
+
+\item{\tt ./lib/} contains libraries.
+
+\item{\tt ./src/} contains the source code for the CCTK
+
+\item {\tt ./toolkits/} contains the Cactus toolkits. The toolkits
+  (the actual ``physics'') is not supplied by the CCTK. If the  toolkits
+  you want to use are part of the central repository, they can be
+  checked out in similar way the CCTK.  Each directory inside {\tt
+    toolkits/} contains thorns. {\q ??}
+\end{itemize}
+
+When Cactus is first compiled it creates a new directory {\tt
+./CCTK/build/}. Disk space may be a problem on supercomputers where
+home directories are small. A workaround is to first create a
+build directory on scratch space, say {\tt scratch/cactus\_build/} (where
+{\tt scratch/} is your scratch directory), and soft link ({\tt ln -s
+scratch/cactus\_build cactus/build/}) it to the Cactus directory.
+
+When the code has been compiled for some configuration CONF, the
+directory {\tt build/CONF/} contains the following:
+
+\begin{itemize}
+
+\item {\tt ActiveThorns} 
+
+\item {\tt datestamp.o}
+
+\item {\tt bindings/} contains all the files created by the perl
+scripts, sorted into subdirectories {\tt Parameters}, 
+{\tt Variables}, {\tt Schedule}, {\tt thorn\_***} (one for each thorn).
+
+\item {\tt build/} contains the post-processed source code, the
+dependencies and the object files, sorted into the subdirectories {\tt
+Cactus}, {\tt CactusBindings} and {\tt thorn\_***}.
+
+\item {\tt config-data} : contains the files created by the configure
+script:
+
+\begin{itemize}
+
+\item {\tt config.cache}
+
+\item {\tt config.h}
+
+\item {\tt config.log}
+
+\item {\tt config.status}
+
+\item {\tt fortran\_name.pl} (used to determine how fortran routines
+are called from C) 
+
+\item {\tt make.config.defn} (contains compilers etc. for a configuration)
+
+\item {\tt make.config.deps}
+
+\item {\tt make.config.rule} (rules to generate object files from source files)
+\end{itemize}
+
+\item {\tt lib} : contains the libraries built from the object files,
+
+\begin{itemize}
+
+\item {\tt libCactus.a} for the flesh
+
+\item{\tt llibCactusBinding.a} for the Bindings 
+
+\item {\tt llib***.a} for each thorn
+
+\end{itemize}
+
+{\q It might be useful to give a couple of commands like nm for seeing
+what is in libraries.}
+
+\item {\tt scratch}: empty at the end.
+
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Getting help}
+
+Cactus Maint and GNATS
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Compilation} 
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+Cactus can be built in different configurations from the same copy of
+the source files, and these different configurations coexist in the
+{\tt cactus/} directory. Here are several cases, where this can be
+useful:
+
+\begin{enumerate}
+\item{}Different configurations can be for {\em different
+architectures}. You can keep executables for multiple architecures
+based on a single copy of soiruce code, shared on a common file
+system.
+\item{} You can compare different {\em compiler options, debug-modes}.
+  You migth want to compile different communication protocols
+  (MPI/GLOBUS) or leave them out all together.
+\item{} You can have different configuration for {\em different thorns
+    collections} compiled into your executable.
+\end{enumerate}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Compilation and configuartions of the CCTK and its Toolkits}
+
+Building the code with GNU make is easy. Use gmake with the following syntax:
+{\t gmake [configuration options] <CONF>}
+
+{\tt gmake} is the GNU make program, {\tt configuration options}
+denotes optional arguments.  The configuration name {\tt CONF}
+references the configuration setting you chose to build. You can pick
+an arbitrary name (e.g. {\tt TEST\_BUILD}), later you can reference this particular
+configuration setting by using that name. The default for {\tt CONF}
+is the name of your operating system (e.g. {\tt LINUX}).
+
+{\q this is not consistent: the first time I can do gmake and it does
+  NOT ask me, if I want to setup IRIX6, e.g. but takes the
+  default. then I DO have to specify 
+  the CONF. IMHO it shoudl always be obligatory.
+  Also, it prompts me, ``do you really want to ... reminds
+  me of windows:-) }
+
+{\q What are the configuration-options ?}
+
+The gmake-process has to be repeated several times.
+
+\begin{enumerate}
+\item{}The first gmake-process configures the CCTK system by picking the
+standard compilers, etc and creates a directory tree in {\tt
+  ./build/CONF} which will later contain the configuration specific
+files. 
+\item{} You will ask to issue {\tt gmake <CONF>} again and you will be
+  presented a list of all thorns the CCTK has found. You will be
+  asked, whether you wish to edit 
+  this list to remove thorns, e.g. Answer {\tt yes} to be able to edit
+  the list with the editor specified in the {\tt \$EDITOR} 
+  environment variable. After closing the editor or answering with {\tt
+    no} the make process will continue. 
+\end{enumerate}
+
+The make process will set up subdirectories in the {\tt ./build}
+directory that contain the configuration specific files. The directory
+structure is 
+\begin{verbatim}
+\end{verbatim}
+
+{\bf Notes and Caveats}
+\begin{itemize}
+\item{} Instead of using the editor to specify the thorns you want to
+  have compiled, you can {\em edit} the {\em ActiveThorns List} outside
+  the make process. It is located in {\tt build/CONF/ActiveThorns},
+  wher {\tt CONF} refers to the name of your configuration.
+  For a completely new configuration, this directory exists {\em
+    after} the first  make phase. 
+\item{} The {\em ActiveThorns List} can also contain the name of a
+  CACTUS Toolkit. In this case all thorns of the Toolkit will be
+  compiled into the executable.
+\item{} If the CCTK {\em cannot find a thorn} you specified, it will
+  repartition you hard disk amd install Windows.
+\item{} {\em GNU make} is required. Error during the build ``{\tt missing
+    seperator}'' are caused by using a different make command.
+\item{} {\em The EDITOR environment variable}. You may not be aware of
+  this, but this thing very often exists and may be set  by default to
+  something scary like vi. If you don't know how to use vi or wish to
+  use your favorite editor instead, reset this environment variable.
+\end{itemize}
+
+{\q move setup file elsewhere.}
+
+{\q move executable elsewhere, and make one for each configuration.}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{gmake targets}
+
+A target for {\tt gmake} can be naively thought of as an argument
+that tells it which of several things listed in the {\tt Makefile} it
+is to do.
+
+\begin{itemize}
+
+\item {\tt gmake CONF} will create the default (uname) configuration
+
+\item {\tt gmake <CONF>-clean} cleans a configuration (rm -r *.o)
+
+\item {\tt gmake <CONF>-delete} deletes a configuration ({\tt rm -r build/<CONF>})
+
+\item {\tt gmake help} lists all make options
+
+\item {\tt gmake tags} creates a {\tt vi} style tags file. See section
+  \ref{sec:TAGS} for using TAGS within Cactus.
+
+\item {\tt gmake TAGS} creates an Emacs style TAGS file. See section
+  \ref{sec:TAGS} for using TAGS within Cactus.
+
+\item {\tt gmake distclean} nukes your build directory.
+
+\item {\tt gmake downsize} removes non essential files as documents
+  and testsuites to allow for minimal installation size.
+
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Compiling in thorns}
+
+{\q This is way to specific for the section ``Compile'' in my opinion.
+This shoudl go with the thorn writing.}
+
+Cactus compiles in all thorns listed in {\tt
+build/CONF/ActiveThorns}. {\q If the thorn has not been checked
+out...It IGNORES ?} Cactus looks for source code in a thorn's {\tt src}
+directory. It first looks for a file {\tt make.code.defn} which
+should contain
+
+\begin{itemize}
+
+\item {\t SRCS = <list of all source files in this directory>}
+
+\item {\t SUBDIRS = <list of all subdirectories containing source files>}
+
+\end{itemize}
+
+and each subdirectory mentioned should also contain a {\tt
+make.code.defn} file with a {\tt SRCS} line ({\tt SUBDIRS} in a
+subdirectory {\tt make.code.defn} file will be ignored).
+
+The {\tt make.code.defn} file in a directory is included at the top of
+the makefile {\q where does it sit?}  used to build the sources. If a
+file {\tt make.code.deps} exists in the directory {\q where?} it is
+included at the bottom.
+
+The standard make system may be overridden by placing a makefile
+called {\tt Makefile} in the {\tt src/} directory.  This can do
+whatever it likes, but must create a library called
+
+{\tt \$(NAME)}
+
+(which is actually {\tt \$(CCTK\_LIBDIR)/lib<thorn>.a }). {\q We need more detail here. What does ``is
+actually'' mean?}
+
+{\q Watch for CCTK here and elsewhere. Don't remove this query before
+CCTK is gone.}
+
+A makefile is passed the following variables
+
+{\q How many makefiles are involved? Which are created at runtime etc.}
+
+\begin{itemize}
+
+\item {\tt \$(CCTK\_HOME)} - the main CCTK directory
+
+\item {\tt \$(TOP)}    - the CONF directory
+
+\item {\tt \$(SRCDIR)} - the directory in which the source files can be found
+
+\item {\tt \$(CONFIG)} - the directory containing the configuration files
+
+\item {\tt \$(THORN)}  - the thorn name
+
+\item {\tt \$(SCRATCH\_BUILD)} - the scratch directory where f90 module
+files should end up if they need to be seen by other thorns.
+
+\item {\tt \$(NAME)}.
+
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Testing} 
+
+simple make and test suite
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+
+{\q Tom, this is for you}
+
+        b) Make methodology (dependencies,libraries, thorn make files
+        etc)
+
+      d) Configuration options
+
+      f) (New platforms??)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Running Cactus}
+
+      a) Command line options
+      b) Simple parameter file syntax (will be explained fully in thorn
+         writers part)
+      c) Description of standard parameters (although maybe should be an
+         appendix)
+      d) Checkpointing and outputting
+      e) Reference to web pages with machine dependant stuff
+      f) Understanding the screen output (RFR tree, errors and warnings etc)
+      g) Convergence mode
+      h) Environment variables
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Looking at output}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+