more doc

git-svn-id: http://svn.cactuscode.org/arrangements/CactusElliptic/EllBase/trunk@7 57bc7290-fb3d-4efd-a9b1-28e84cce6043

1 files changed, 50 insertions, 39 deletions

diff --git a/doc/ThornGuide.tex b/doc/ThornGuide.tex
index b1b0173..c4ba69f 100644
--- a/doc/ThornGuide.tex
+++ b/doc/ThornGuide.tex
@@ -3,24 +3,27 @@
 
 \begin{document}
 
-\chapter{IDAnalyticBH}
+\chapter{EllBase}
 
 \begin{tabular}{@{}ll}
 Code Authors & Gerd Lanfermann \\
 Maintained by & Cactus Developers \\
-Documentation Authors & 
+Documentation Authors & Gerd Lanfermann
 \end{tabular}
 
 \section{Introduction}
-  
+We a give a bried introduction to the elliptic solver interfaces
+provided by {\tt EllBase}. Further down, we explain how to implement a 
+new elliptic equations class and how to connect am elliptic  solver to it.
+We do not discuss any elliptic solvers here, please refer to the
+elliptic solver thorns.
 \subsection{Purpose of Thorn}
 
 Thorn EllBase provides the basic functionality to register a class of
 ellitpic equations and register solver for that particular class.
 The solvers are called by the user through a unique interface, which calls the 
 elliptic solver requested by passing through the name under which the solver 
-routine is  registered.
-EllBase defines four basic elliptic classes and offers two solver 
+routine is  registered. {\tt EllBase} defines four basic elliptic classes and offers two solver 
 (SOR and PETSc) for each class.
 
 The elliptic classes supported by this thorn in three dimensions are
@@ -44,9 +47,9 @@ given metric and a conformal factor.
 
 \end{itemize}
 
-\subsubsection{Using EllBase}
+\subsection{Using EllBase}
 
-EllBase by itself does not provide any ellitpic solving capabilities. 
+EllBase by itself does not provide any elliptic solving capabilities. 
 It merely provides the registration structure and calling interface.
 
 The idea of a unified calling interface can be motivated as follows: 
@@ -87,7 +90,7 @@ for this elliptic problem has been registered.
 The registration process is part of the authors thorn, not part of EllBase. 
 There is no need to change code in EllBase. Usually, a author of solver 
 routines will register the routines that register an elliptic equation class 
-and/or an elliptic solver at STARTUP (see \ref{se:RFR} for information on
+and/or an elliptic solver at STARTUP (see \ref{sec:RFR} for information on
  scheduling). If a author registers both, class and solver, you must make 
 sure, that the elliptic class is registered {\em before} the solver 
 registration takes place. 
@@ -100,25 +103,31 @@ some of the functionality needed in the registration code can only be
 achieved in C, a basic knowledge of C is helpful.
 
 \begin{itemize}
-\item{\bf Assumption}: The elliptic equation we want to solve is of type XXX. 
-The solver for this elliptic equation will be called ``FastSOR_solver''
-and will be written in Fortran. Since Fortran cannot be called directly, we
-need to have C wrapper function ``FastSOR_wrapper''. The elliptic equation 
-class will be called ``SimpleEllClass'': it will be flat space solver, 
+\item{\bf Assumption}:
+\begin{itemize} 
+\item{}The elliptic equation 
+class will be called ``{\em SimpleEllClass}'': it will be flat space solver, 
 that only 
-takes the coefficient matrix $M$. (Note that this solver class is already 
-provided by
-EllBase.)
-The name of the demonstration thorn will be 
-``ThornFastSOR''. Since I will only demonstrate the registration priciple 
+takes the coefficient matrix $M$: 
+%\begin{equation}
+%\nabla \phi - M \phi \eq 0
+%\end{equation}
+Note that this solver class is already provided by EllBase.
+\item{}The name of the demonstration thorn will be 
+``{\tt ThornFastSOR}''. Since I will only demonstrate the registration priciple 
 and calling structure, I leave it to the interested reader to write a really 
 fast SOR solver.
+\item{}The solver for this elliptic equation will be called ``{\tt FastSOR\_solver}''
+and will be written in Fortran. Since Fortran cannot be called
+directly by the registration mechanism, we
+need to have C wrapper function ``{\tt FastSOR\_wrapper}''. 
+\end{itemize}
 
-\item{\bf Elliptic class declaration}: {\tt SimpleEllThorn/src/SimpleEll_Class.c} 
+\item{\bf Elliptic class declaration}: {\tt SimpleEllThorn/src/SimpleEll\_Class.c} 
 \begin{verbatim}
 \end{verbatim}
 
-\item{\bf Elliptic solver interface}: {\tt src/SimpleEll_Interface.c}
+\item{\bf Elliptic solver interface}: {\tt src/SimpleEll\_Interface.c}
 \begin{verbatim}
 
 #include ``cctk.h''
@@ -134,12 +143,12 @@ void Ell_SimpleEllSolverRegistry(void (*solver_func), const char *solver_name)
   StoreNamedData(&SimpleEllSolverDB,solver_name,(void*)solver_func);
 }
 \end{verbatim}
-The routine above registers the solver (or better the function pointer of the solver routine ``*solve_func'') for the equation class 
-{\em SimpleEllClass} by the name {\tt solver_name} in the database {\tt
+The routine above registers the solver (or better the function pointer of the solver routine ``*solve\_func'') for the equation class 
+{\em SimpleEllClass} by the name {\tt solver\_name} in the database {\tt
 SimpleEllSolverDB}. This database is declared in statment {\tt static pNamedData...}.
 
 
-Next, we write our interface in the same file {\tt ./SimpleEll_Interface.c}:
+Next, we write our interface in the same file {\tt ./SimpleEll\_Interface.c}:
 \begin{verbatim}
 void Ell_SimpleEllSolver(cGH *GH, int *FieldIndex, int *MIndex, 
 		         CCTK_REAL *AbsTol, CCTK_REAL *RelTol,
@@ -161,9 +170,9 @@ void Ell_SimpleEllSolver(cGH *GH, int *FieldIndex, int *MIndex,
 }
 
 \end{verbatim}
-The interface {\tt Ell_SimpleEllSolver} is called from the user side. It receives a pointer to the grid hierarchy, the ID-number of the field to solver for, two arrays which the used upload with convergence test info, and finally, the name of the solver the user want to employ {\tt *solver_name}. {\bf Note:} all these quantities are referenced by pointers, hence the ``*''.
+The interface {\tt Ell\_SimpleEllSolver} is called from the user side. It receives a pointer to the grid hierarchy, the ID-number of the field to solver for, two arrays which the used upload with convergence test info, and finally, the name of the solver the user want to employ {\tt *solver\_name}. {\bf Note:} all these quantities are referenced by pointers, hence the ``*''.
 
-Within the interface, the solver_name is used to get the pointer to function which was registered under this name.
+Within the interface, the solver\_name is used to get the pointer to function which was registered under this name.
 Once the function is known, it called with all the arguments passed to 
 the interface.
 
@@ -171,7 +180,7 @@ To allow calls from Fortran, the interface in C needs to be ``wrapped''.
 (This wrapping  is different from the one necessary to make to actual solver 
 accessible by the elliptic registry).
 
-\begin{verbatm}
+\begin{verbatim}
 /* Fortran wrappr for the routine Ell_SimpleEllSolver */
 void FMODIFIER FORTRAN_NAME(Ell_SimpelEllSolver)
      (cGH *GH, int *FieldIndex, int *MIndex, 
@@ -184,7 +193,7 @@ void FMODIFIER FORTRAN_NAME(Ell_SimpelEllSolver)
 }
 \end{verbatim}
 
-\item{\bf Elliptic solver}:{\tt ./src/FastSOR_solver.F}\\
+\item{\bf Elliptic solver}:{\tt ./src/FastSOR\_solver.F}\\
 Here we show the first lines of the Fortran code for the solver:
 
 \begin{verbatim}
@@ -217,15 +226,15 @@ c     We have no storage for M if they are of size one in each direction
 
 \end{verbatim}
 This Fortran solver receives the following arguments: the ``typical''
- CCTK_ARGUMENTS({\tt  (see \ref{sec:cctk_arguments}): {\tt \_CCTK\_FARGUMENTS},
-the {\em size} of the coefficient matrix: {\tt Mlinear_lsh}, the coefficient
+ CCTK\_ARGUMENTS (see \ref{sec:cctk_arguments}): {\tt \_CCTK\_FARGUMENTS},
+the {\em size} of the coefficient matrix: {\tt Mlinear\_lsh}, the coefficient
 matrix {\tt Mlinear}, the variable to solve for: {\tt var}, and the two arrays with convergence information. 
 
 In the declaration section, we delcare: the cctk arguments, the Mlinear size array, the coefficient matrix, by the 3-dim. size array, the variable to solve for. Why do we pass the size of Mlinear explicitly and do not use the 
-{\tt cctk_lsh} (processor local shape of a grid function) as we did for {\tt var} ? The reason is the following: while we can expect the storage of {\tt var} to be {\em on} for the solve, there is no reason (in a more general elliptic case) to assume, that the coefficient 
-matrix has storage allocated, perhaps it is not needed at all! In this case, we have to protect ourself against referencing empty arrays. For this reason, we also employ the flag {\tt Mlinear_storage}.
+{\tt cctk\_lsh} (processor local shape of a grid function) as we did for {\tt var} ? The reason is the following: while we can expect the storage of {\tt var} to be {\em on} for the solve, there is no reason (in a more general elliptic case) to assume, that the coefficient 
+matrix has storage allocated, perhaps it is not needed at all! In this case, we have to protect ourself against referencing empty arrays. For this reason, we also employ the flag {\tt Mlinear\_storage}.
 
-\item{\bf Elliptic solver wrapper}:{\tt ./src/FastSOR_wrapper.c}\\
+\item{\bf Elliptic solver wrapper}:{\tt ./src/FastSOR\_wrapper.c}\\
 The Fortran solver can not be used within the elliptic registry directly. 
 Instead the Fortran code is called through a wrapper:
 \begin{verbatim}
@@ -257,12 +266,12 @@ void FastSOR_wrapper(cGH *GH, int *FieldIndex, int *MIndex,
 }
 \end{verbatim}
 
-The wrapper {\tt FastSOR_wrapper} takes these arguments: the indices 
+The wrapper {\tt FastSOR\_wrapper} takes these arguments: the indices 
 of the field to solve for ({\tt FieldIndex}) and the coefficient matrix 
 ({\tt MIndex}), the two arrays containing
 convergence information ({\tt AbsTol, RelTol}). 
-In the body of the programm we provide two CCTK_REAL pointers to the 
-data section of the field to solver ({\tt var, Mlinear}) by means of {\tt Get_VarDataPtrI}. For Mlinear, we only do this, if the index is non-negative. 
+In the body of the programm we provide two CCTK\_REAL pointers to the 
+data section of the field to solver ({\tt var, Mlinear}) by means of {\tt Get\_VarDataPtrI}. For Mlinear, we only do this, if the index is non-negative. 
 A negative index is a signal by the user that the coefficient matrix has 
 no storage allocated.(For more general elliptic equation cases, e.g. no 
 source terms.)
@@ -270,8 +279,9 @@ source terms.)
 
 
 \item{\bf Elliptic solver startup}: {\tt ./src/Startup.c}\\
-The routine below in {\tt Startup.c} performs the registration of our solver wrapper {\tt FastSOR_wrapper} under the name ``{\em fastsor}'' for the elliptic class ``{\em Ell_SimpleEll}''. We do not register with the solver interface 
-{\tt Ell_SimpleEllSolver} directly, but with the class.
+The routine below in {\tt Startup.c} performs the registration of our solver wrapper {\tt FastSOR\_wrapper} under the name ``{\em fastsor}'' for the elliptic class ``{\em Ell\_SimpleEll}''. We do not register with the solver interface 
+{\tt Ell\_SimpleEllSolver} directly, but with the class. In {\tt
+Startup,c} we have:
 \begin{verbatim}
 #include ``cctk.h''
 #include ``cctk_parameters.h''
@@ -286,12 +296,12 @@ void FastSOR_register(cGH *GH) {
 }
 \end{verbatim}
 Note that more solver registration code could be put here (registration 
-for other classes, e.g.)
+for other classes, etc.)
 
 
 \item{\bf Elliptic solver scheduling}: {\tt schedule.ccl}
 We schedule the registratio of the fast SOR solver at FIXME, by this time, 
-{\em the elliptic class} {\tt Ell_SimpleEll} has already been registered. 
+{\em the elliptic class} {\tt Ell\_SimpleEll} has already been registered. 
 \begin{verbatim}
 schedule FastSOR_register at CCTK_INITIAL
 {
@@ -300,5 +310,6 @@ schedule FastSOR_register at CCTK_INITIAL
 \end{verbatim}
 
 
+\end{itemize}
 
 \end{document}