diff options
author | allen <allen@17b73243-c579-4c4c-a9d2-2d5706c11dac> | 1999-09-25 10:50:04 +0000 |
---|---|---|
committer | allen <allen@17b73243-c579-4c4c-a9d2-2d5706c11dac> | 1999-09-25 10:50:04 +0000 |
commit | ffad0fbe3962b59b0b548797a513fb13dad7cccd (patch) | |
tree | f473bf0fadfe948b0b6191dd432eea257b0ae5ab | |
parent | 49e7fabc728f09c40d251e4198dc4d8ad255769e (diff) |
More changes
git-svn-id: http://svn.cactuscode.org/flesh/trunk@994 17b73243-c579-4c4c-a9d2-2d5706c11dac
-rw-r--r-- | doc/UsersGuide/Appendices.tex | 2 | ||||
-rw-r--r-- | doc/UsersGuide/Infrastructure.tex | 115 | ||||
-rw-r--r-- | doc/UsersGuide/Preface.tex | 10 | ||||
-rw-r--r-- | doc/UsersGuide/RunningCactus.tex | 187 | ||||
-rw-r--r-- | doc/UsersGuide/ThornWriters.tex | 14 |
5 files changed, 136 insertions, 192 deletions
diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex index 9fb1b9eb..4b421e46 100644 --- a/doc/UsersGuide/Appendices.tex +++ b/doc/UsersGuide/Appendices.tex @@ -19,6 +19,7 @@ that the thorn configuration files are written in. \item[{\tt CVS}] The {\em ``Concurrent Versioning System''} is the favoured distribution system for Cactus and can be downloaded from your favorite GNU site. +\item[{\tt driver}] A thorn which creates and handles grid hierachies \item[{\tt flesh}] The routines which hold all the thorns together, this is what you get if you check out {\tt Cactus} from our CVS repository. \item[{\tt friend}] @@ -38,6 +39,7 @@ is what you get if you check out {\tt Cactus} from our CVS repository. \item[{\tt MPI}] \item[{\tt parameter}] A variable which remains unchanged throughout the executation of a Cactus executable. Parameters all have default values which can be changed in a parameter file. \item[{\tt processor topology}] +\item[{\tt PUGH}] The default parallel driver for Cactus which uses MPI. \item[{\tt PVM}] \item[{\tt reduction}] \item[{\tt TAGS}] diff --git a/doc/UsersGuide/Infrastructure.tex b/doc/UsersGuide/Infrastructure.tex index 3d3babf0..5ef50aa8 100644 --- a/doc/UsersGuide/Infrastructure.tex +++ b/doc/UsersGuide/Infrastructure.tex @@ -1,81 +1,60 @@ \begin{cactuspart}{3}{Infrastructure Thorn Writer's Guide}{$RCSfile$}{$Revision$} \renewcommand{\thepage}{\Alph{part}\arabic{page}} -\begin{enumerate} +\chapter{Introduction} +\label{sec:in} - \item{} Concepts and Terminology (Overloading and registration of functions) +\begin{itemize} + \item{} Concepts and terminology (Overloading and registration of functions) \item{} The cGH structure --- what it is and how to use it \item{} Extending the cGH structure - \item{} Querying Group and Variable Information + \item{} Querying group and variable information \item{} Providing an IO layer \item{} Providing a communication layer - \item{} Doing more --- replacing the rest of the code - \item{} Appendices - \begin{itemize} - \item{} Overloadable Functions in the F***h - \begin{itemize} - \item{} Main - \begin{itemize} - \item{} {\t int CCTK\_Initialise(tFleshConfig *)} - \item{} {\t int CCTK\_Evolve(tFleshConfig *)} - \item{} {\t int CCTK\_Shutdown(tFleshconfig *)} - \item{} Defaults - \end{itemize} - \item{} IO - \begin{itemize} - \item{} {\t int CCTK\_OutputGH(cGH *GH)} - \item{} {\t int CCTK\_OutputVarAsByMethod(cGH *GH, const char *var, - const char *method, const char *alias)} - \item{} Defaults - \begin{itemize} - \item{} {\t CCTK\_OutputGH} - \item{} {\t CCTK\_OutputVarAsByMethod} - \end{itemize} - \end{itemize} - \item{} Comm - \begin{itemize} - \item{} {\t int CCTK\_SyncGroup(cGH *GH, const char *group)} - \item{} {\t int CCTK\_EnableGroupStorage(cGH *GH, const char *group)} - \item{} {\t int CCTK\_DisableGroupStorage(cGH *GH, const char *group)} - \item{} {\t int CCTK\_EnableGroupComm(cGH *GH, const char *group)} - \item{} {\t int CCTK\_DisableGroupComm(cGH *GH, const char *group)} - \item{} {\t int CCTK\_Barrier(cGH *GH)} - \item{} {\t int CCTK\_Reduce(cGH *GH, const char *operation, - int n\_infields, int n\_outfields, - int out\_type, void **outarray, ...)} - \item{} {\t int CCTK\_Interp(cGH *GH, const char *operation, - int n\_coords, int n\_infields, int n\_outfields, - int n\_points, int type, ...)} - \item{} {\t int CCTK\_ParallelInit(cGH *GH)} - \item{} {\t int CCTK\_Init(cGH *GH)} - \item{} {\t int CCTK\_Exit(cGH *GH)} - \item{} {\t int CCTK\_Abort(cGH *GH)} - \item{} {\t cGH *CCTK\_SetupGH(tFleshConfig *config, int convergence\_level)} - \item{} Defaults - \begin{itemize} - \item{} {\t CCTK\_SetupGH} - \end{itemize} - \end{itemize} - \end{itemize} - \item{} Registerable Functions in the F***h - \begin{itemize} - \item{} Main - \begin{itemize} - \item{} Defaults - \end{itemize} - \item{} IO - \begin{itemize} - \item{} Defaults - \end{itemize} - \item{} Comm - \begin{itemize} - \item{} Defaults - \end{itemize} - \end{itemize} - \end{itemize} -\end{enumerate} + \item{} Providing a reduction operator + \item{} Providing an interpolation operator + \item{} Overloadable functions +\end{itemize} + \section{Overloadable functions} + + \subsection{Core functions} + \begin{tabular}{|l|l|} + \hline {\bf Function} & {\bf Default} \\ + \hline {\t CCTK\_Initialise} &\\ + \hline {\t CCTK\_Evolve} &\\ + \hline {\t CCTK\_Shutdown} &\\ + \hline + \end{tabular} + + \subsection{IO Functions} + \begin{tabular}{|l|l|} + \hline {\bf Function} & {\bf Default} \\ + \hline {\t CCTK\_OutputGH} & \\ + \hline {\t CCTK\_OutputVarAsByMethod} & \\ + \hline + \end{tabular} + + \subsection{Driver functions} + \begin{tabular}{|l|l|} + \hline {\bf Function} & {\bf Default} \\ + \hline {\t CCTK\_SyncGroup} &\\ + \hline {\t CCTK\_EnableGroupStorage} &\\ + \hline {\t CCTK\_DisableGroupStorage} &\\ + \hline {\t CCTK\_EnableGroupComm} &\\ + \hline {\t CCTK\_DisableGroupComm} &\\ + \hline {\t CCTK\_Barrier} &\\ + \hline {\t CCTK\_Reduce} &\\ + \hline {\t CCTK\_Interp} &\\ + \hline {\t CCTK\_ParallelInit} &\\ + \hline {\t CCTK\_Init} &\\ + \hline {\t CCTK\_Exit} &\\ + \hline {\t CCTK\_Abort} &\\ + \hline {\t CCTK\_SetupGH} &\\ + \hline + \end{tabular} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \end{cactuspart} diff --git a/doc/UsersGuide/Preface.tex b/doc/UsersGuide/Preface.tex index b68a2d3e..8801e2f6 100644 --- a/doc/UsersGuide/Preface.tex +++ b/doc/UsersGuide/Preface.tex @@ -54,13 +54,14 @@ Other topics to be discussed in separate documents include: \begin{Lentry} -\item [Computational Thorn Guide] This will contain details about the +\item [{\bf Computational Thorn Guide}] This will contain details about the arrangements and thorns making up the standard Cactus Computation Tool Kit -\item [Relativity Thorn Guide] This will contain details about the arrangements and thorns making up the Cactus Relativity Tool Kit, one of the major +\item [{\bf Relativity Thorn Guide}] This will contain details about the arrangements and thorns making up the Cactus Relativity Tool Kit, one of the major motivators, and still the driving force, for the Cactus Code. -\item [Flesh Maintainers Guide] This will contain all the gruesome details +\item [{\bf Flesh Maintainers Guide}] + This will contain all the gruesome details about the inner workings of Cactus, for all those who want or need to expand or maintain the core of Cactus. @@ -99,5 +100,6 @@ Germany Hearty thanks to all those who have helped with documentation for the Cactus Code. Special thanks to those who struggled with the earliest sparce versions of this guide and sent in mistakes and suggestions, -in particular John Baker, Sai Iyer, Paul Lamping, Ed Seidel. +in particular John Baker, Ginny Hudak-David, Sai Iyer, Paul Lamping, +Nancy Tran and Ed Seidel. diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex index 22ed41c9..e9f13140 100644 --- a/doc/UsersGuide/RunningCactus.tex +++ b/doc/UsersGuide/RunningCactus.tex @@ -17,59 +17,59 @@ In general, Cactus {\em requires} the following set of software to function in single processor mode. Please refer to the architecture section \ref{sec:suar} for architecture specific items. -\begin{itemize} -\item{\tt Perl5.0} Perl is used extensively during the Cactus +\begin{Lentry} +\item[{\tt Perl5.0}] Perl is used extensively during the Cactus thorn configuration phase. Perl is available for nearly all operating systems known to man and can be obtained at {\tt http://www.perl.org} -\item{\tt GNU make} The make +\item[{\tt GNU make}] The make process works with the GNU make utility (referred to as {\bf gmake} henceforth). While other make utilities may also work, this is not guaranteed. Gmake can be obtained from your favorite GNU site or from {\tt www.gnu.org} -\item{\tt C/C++} C and C++ compiler. For example, the GNU compilers. These +\item[{\tt C/C++}] C and C++ compiler. For example, the GNU compilers. These are available for most supported platforms. Platform specific compilers should also work. -\item{\tt CVS} The {\em ``Concurrent Versioning System''} is not needed +\item[{\tt CVS}] The {\em ``Concurrent Versioning System''} is not needed to run/compile Cactus, 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. Tar files of each release are also available. -\end{itemize} +\end{Lentry} \noindent -To use Cactus, with the default driver (CactusPUGH/PUGH) on multiple -processers you also need: -\begin{itemize} -\item{\tt MPI} the {\it Message Passing Interface (MPI)} +To use Cactus, with the default driver ({\tt CactusPUGH/PUGH}) on multiple +processors you also need: +\begin{Lentry} +\item[{\tt MPI}] the {\it Message Passing Interface (MPI)} which provides inter-processor communication. -Supercomputering sites often supply a native MPI implementation with +Supercomputering sites often supply a native {\tt MPI} implementation with which Cactus is very likely to be compatible. Otherwise there are various freely available ones available, e.g. the {\tt MPICH} -version of MPI is available for various architectures and operating +version of {\tt MPI} is available for various architectures and operating systems at {\tt http://www-unix.mcs.anl.gov/mpi/}. -\end{itemize} +\end{Lentry} \noindent If you are using any thorns containing routines written in {\tt FORTRAN} you also need -\begin{itemize} -\item{\tt F90/F77} For routines written in F77, either an F90 or an F77 +\begin{Lentry} +\item[{\tt F90/F77}] For routines written in F77, either an F90 or an F77 compiler can be used. For routines written in F90 a F90 compiler is obviously required. There is a very limited set of free F90 compilers available for the different architectures. -\end{itemize} +\end{Lentry} \noindent While not required for compiling or running Cactus, for thorn development it is useful to install -\begin{itemize} -\item{\tt ctags/etags}: The program Tags enables you browse through the calling structure +\begin{Lentry} +\item[{\tt ctags/etags}] The program Tags enables you browse through the calling structure of a program by help of function call database. Navigating the flesh and arrangements becomes very easy. Emacs and vi both support this method. See \ref{sec:usta} for a short guide to ``tags''. -\end{itemize} +\end{Lentry} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -84,13 +84,14 @@ Cactus on, including some architecture specific notes. \item[{\bf SGI} 32 or 64 bit running Irix] \item[{\bf Cray T3E}] \item[{\bf Dec Alpha}] Dec operating system and Linux. Single processor - mode and MPI supported. The Decs need to have the GNU {\tt C/C++} + mode and {\tt MPI} 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.psrv.com} - -- the only free we know of. Single processor mode and MPICH + -- the only free we know of. Single processor mode and {\tt MPICH}, {\tt LAM} supported. -\item[{\bf Windows NT}] Compiles with Cygwin version B20, Digital Fortran Compiler and Microsoft Visual C++ compiler. +\item[{\bf Windows NT}] Compiles with Cygwin version B20, Digital Fortran Compiler and Microsoft Visual C++ compiler. Single processor mode and {\tt WMPI}, +{\tt HPVM} supported. \end{Lentry} The following machines are only partially supported @@ -436,59 +437,20 @@ values will be valid on all architectures. The name of the executable. \end{Lentry} -\item {\tt Compile System Vagueries} - -The following options are required to accomodate the odd behaviour -of compilers on a few platforms - -\begin{Lentry} - -\item {\tt CCOMPILEONLY} Flag to instruct the C compiler to compile to an object file and not to invoke the linker - -\item {\tt FCOMPILEONLY} Flag to instruct the Fortran compiler to compile to an object file and not to invoke the linker - -\item [{\tt CREATEEXE}] Flag for naming executable, most compilers use - {\tt -o}, but alas some don't - -\item [{\tt DIRSEP}] Directory name separator - -\item [{\tt EMPTY\_VAR}] {\bf FIXME: What is this} - -\item [{\tt OPTIONSEP}] {\bf FIXME: What is this} - -\item [{\tt CACTUSLIBLINKLINE}] Some architectures need something special for linking in libraries - -\item [{\tt C\_DEPEND}] -\item [{\tt CXX\_DEPEND}] -\item [{\tt F\_DEPEND}] -\item [{\tt F77\_DEPEND}] - -\item [{\tt C\_DEPEND\_OUT}] -\item [{\tt CXX\_DEPEND\_OUT}] -\item [{\tt F\_DEPEND\_OUT}] -\item [{\tt F77\_DEPEND\_OUT}] - -\item [{\tt GET\_WD}] Command to get the current working directory - -\item [{\tt GENERAL\_LIBRARIES}] Command to generate the link line for libraries - -\end{Lentry} - \item{\tt Extra packages} Compiling with extra packages is described fully in Section \ref{sec:cowiexpa}, which should be consulted for the full range of configuration options. -\begin{itemize} -\item {\tt MPI} -*The MPI package to use, if required. Supported values are - CUSTOM, NATIVE, MPICH or LAM +\begin{Lentry} +\item [{\tt MPI} *] The {\tt MPI} package to use, if required. Supported values are + {\tt CUSTOM}, {\tt NATIVE}, {\tt MPICH} or {\tt LAM} -\item {\tt HDF5} +\item [{\tt HDF5}] Supported values are YES -\end{itemize} +\end{Lentry} \end{itemize} @@ -516,53 +478,53 @@ To compile with MPI, the configure option is where {\tt <MPI\_TYPE>} can take the values (entries followed by * may be specified on the configuration command line): -\begin{itemize} +\begin{Lentry} -\item{} CUSTOM For a custom MPI configuation set the variables - \begin{itemize} - \item {\tt MPI\_LIBS} * libraries - \item {\tt MPI\_LIB\_DIRS} * library directories - \item {\tt MPI\_INC\_DIRS} * include file directories - \end{itemize} +\item[{\tt CUSTOM}] For a custom {\tt MPI} configuation set the variables + \begin{Lentry} + \item [{\tt MPI\_LIBS} *] libraries + \item [{\tt MPI\_LIB\_DIRS} *] library directories + \item [{\tt MPI\_INC\_DIRS} *] include file directories + \end{Lentry} -\item{} NATIVE Use the native MPI for this machine, as indicated in +\item[{\tt NATIVE}] Use the native {\tt MPI} for this machine, as indicated in the {\tt known-architectures} directory ({\tt lib/make/known-architectures}) -\item{} MPICH +\item[{\tt MPICH}] Use MPICH ({\tt http://www-unix.mcs.anl.gov/mpi/mpich}). This is controlled by the options - \begin{itemize} - \item {\tt MPICH\_DIR} * directory in which MPICH is installed. + \begin{Lentry} + \item [{\tt MPICH\_DIR} *] directory in which {\tt MPICH} is installed. If this option is not defined it will be searched for. - \item {\tt MPICH\_DEVICE} * the device used by MPICH. If not + \item [{\tt MPICH\_DEVICE} *] the device used by {\tt MPICH}. If not defined, the configuration process will search for this in a few defined places. Supported devices are currently {\tt ch\_p4}, {\tt ch\_shmem}, and {\tt globus}, and they are searched for in this order. - \end{itemize} + \end{Lentry} If {\tt MPICH\_DEVICE} is chosen to be Globus, (www.globus.org), an additional variable must be set - \begin{itemize} - \item{} {\tt GLOBUS\_LIB\_DIR} * directory in which Globus libraries are installed - \end{itemize} + \begin{Lentry} + \item[{\tt GLOBUS\_LIB\_DIR} *] directory in which Globus libraries are installed + \end{Lentry} -\item{} LAM -Use LAM (Local Area Multicomputer, {\tt http://www.mpi.nd.edu/lam/}). This is +\item[{\tt LAM}] +Use {\tt LAM} (Local Area Multicomputer, {\tt http://www.mpi.nd.edu/lam/}). This is controlled by the variable - \begin{itemize} - \item{} {\tt LAM\_DIR} * directory in which LAM is installed. This + \begin{Lentry} + \item[{\tt LAM\_DIR} *] directory in which {\tt LAM} is installed. This will be searched for, in a few provided places, if not given. - \end{itemize} + \end{Lentry} -\item{} WMPI +\item[{\tt WMPI}] Use WMPI (Win32 Message Passing Interface, {\tt http://dsg.dei.uc.pt/w32mpi/intro.html}). This is controlled by the variable - \begin{itemize} - \item{} {\tt WMPI\_DIR} * directory in which WMPI is installed. - \end{itemize} + \begin{Lentry} + \item[{\tt WMPI\_DIR} *] directory in which {\tt WMPI} is installed. + \end{Lentry} -\end{itemize} +\end{Lentry} Note that the searches for libraries etc. mentions above use the locations given in the files in {\tt lib/make/extras/MPI}. @@ -762,13 +724,13 @@ An {\it option} for gmake can be thought of as an argument which tells it how it should make a {\tt target}. Note that the final result is always the same. -\begin{itemize} +\begin{Lentry} -\item {\tt gmake <target> SILENT=no} prints the commands that gmake is executing -\item {\tt gmake <target> TJOBS=<number>} compile in parallel, across thorns -\item {\tt gmake <target> FJOBS=<number>} compile in parallel, across files within each thorn +\item [{\tt gmake <target> SILENT=no}] prints the commands that gmake is executing +\item [{\tt gmake <target> TJOBS=<number>}] compile in parallel, across thorns +\item [{\tt gmake <target> FJOBS=<number>}] compile in parallel, across files within each thorn -\end{itemize} +\end{Lentry} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -779,27 +741,26 @@ the same. \section{Other gmake targets} -\begin{itemize} - +\begin{Lentry} -\item {\tt gmake help} lists all make options +\item [{\tt gmake help}] lists all make options -\item {\tt gmake tags} creates a {\tt vi} style tags file. See section +\item [{\tt gmake tags}] creates a {\tt vi} style tags file. See section \ref{sec:usta} for using TAGS within Cactus. -\item {\tt gmake TAGS} creates an Emacs style TAGS file. See section +\item [{\tt gmake TAGS}] creates an Emacs style TAGS file. See section \ref{sec:usta} for using TAGS within Cactus. -\item {\tt gmake doc} places a postscript version of the Users Guide documentation in your Cactus home directory. +\item [{\tt gmake doc}] places a postscript version of the Users Guide documentation in your Cactus home directory. -\item {\tt gmake checkout} allows you to easily checkout Cactus arrangements and thorns. +\item [{\tt gmake checkout}] allows you to easily checkout Cactus arrangements and thorns. -\item {\tt gmake distclean} delete your {\tt configs} directory and hence all your configurations. +\item [{\tt gmake distclean}] delete your {\tt configs} directory and hence all your configurations. -\item {\tt gmake downsize} removes non essential files as documents +\item [{\tt gmake downsize}] removes non essential files as documents and testsuites to allow for minimal installation size. -\end{itemize} +\end{Lentry} \section{Testing} @@ -815,14 +776,14 @@ for the thorns you have compiled use These testsuites serve the dual purpose of -\begin{itemize} -\item {\tt Regression testing} +\begin{Lentry} +\item [Regression testing] i.e. making sure that changes to the thorn or the flesh don't affect the output from a known parameter file. -\item {\tt Portability testing} +\item [Portability testing] i.e. checking that the results are independent of the architecture - this is also of use when trying to get Cactus to work on a new architecture. -\end{itemize} +\end{Lentry} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -990,7 +951,7 @@ order that they will be executed. For example {\tt \begin{verbatim} --------------------------------------------------------------------------------- +---------------------------------------------------------------------- Startup routines Cactus: Register banner for Cactus CartGrid3D: Register GH Extension for GridSymmetry @@ -1018,7 +979,7 @@ order that they will be executed. For example if (analysis) endif enddo --------------------------------------------------------------------------------- +---------------------------------------------------------------------- \end{verbatim} } diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex index 020bfd70..157c06f1 100644 --- a/doc/UsersGuide/ThornWriters.tex +++ b/doc/UsersGuide/ThornWriters.tex @@ -19,7 +19,7 @@ and all your evolution thorns in another arrangement, or to have separate arrangements for your development, private and shared thorns. -The arrangements live in the `arrangements' directory off the main +The arrangements live in the {\tt arrangements} directory off the main Cactus directory. Arrangement names must be unique, and cannot start with a `\#', or finish with `\~{}' or `.bak'. @@ -43,7 +43,7 @@ without affecting any other thorn. An {\bf implementation} defines a group of variables and parameters which are used to implement some functionality. For example the thorn -{\tt CactusPUGH/PUGH} provides the implementation {\tt driver}. This +{\tt CactusPUGH/PUGH} provides the implementation {\it driver}. This implementation is responsible for providing memory for grid variables and for communication. Another thorn can also implement {\tt driver}, and both thorns can be compiled in {\em at the same time}. @@ -113,22 +113,22 @@ by various configuration files. These consist of: -\begin{itemize} +\begin{Lentry} -\item {\tt interface.ccl} +\item [{\tt interface.ccl}] This defines the {\bf implementation} (Section~\ref{sec:im}) the thorn provides, and the variables the thorn needs, along with their visibility to other implementations. -\item {\tt param.ccl} +\item [{\tt param.ccl}] This defines the parameters that are used to control the thorn, along with their visibility to other implementations. -\item {\tt schedule.ccl} +\item [{\tt schedule.ccl}] This defines which functions from the thorn are called and when they are called. -\end{itemize} +\end{Lentry} \subsection{General syntax of CCL files} |