Elliptic Documentation pretty complete

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

1 files changed, 228 insertions, 39 deletions

diff --git a/doc/ThornGuide.tex b/doc/ThornGuide.tex
index c4ba69f..72a697a 100644
--- a/doc/ThornGuide.tex
+++ b/doc/ThornGuide.tex
@@ -12,15 +12,15 @@ Documentation Authors & Gerd Lanfermann
 \end{tabular}
 
 \section{Introduction}
-We a give a bried introduction to the elliptic solver interfaces
+We a give a brief 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.
+new elliptic equations class and how to connect an 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.
+elliptic 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. {\tt EllBase} defines four basic elliptic classes and offers two solver 
@@ -28,26 +28,226 @@ routine is  registered. {\tt EllBase} defines four basic elliptic classes and of
 
 The elliptic classes supported by this thorn in three dimensions are
 \begin{enumerate}
-\item{\em flat:} solves a linear elliptic equation is flat space.
-\item{\em metric:} solves a linear elliptic equation for a given metric
-\item{\em conformal metric:} solves a linear elliptic equation for a
-given metric and a conformal factor.
-\item{\em generic:} solves a linear elliptic equation by passing the 
+\item{\bf flat:} {\tt Ell\_LinFlat}\\
+solves a linear elliptic equation is flat space: $\nabla \phi - M \phi
+- N = 0 $
+
+\item{\bf metric:} {\tt Ell\_LinMetric}\\
+solves a linear elliptic equation for a given metric: $\nabla_{g} \phi
+- M \phi - N = 0 $
+\item{\bf conformal metric:} {\tt Ell\_LinConfMetric}\\
+ solves a linear elliptic equation for a
+given metric and a conformal factor: $\nabla_{cg} \phi - M \phi
+- N = 0 $
+\item{\bf generic:} solves a linear elliptic equation by passing the 
 	stencil functions. There is support for a maximum of 27 stencil 
-	functions ($3^3$).
+	functions ($3^3$). {\em This is not implemented, yet}
 \end{enumerate}
 
-\subsection{Technical Specification}
+\section{Technical Specification}
 
 \begin{itemize}
 
-\item{Implements} ellbase
-\item{Inherits from} grid
-\item{Tested with thorns} EllTest
+\item{Implements:} {\tt ellbase}
+\item{Inherits from:} {\tt grid}
+\item{Tested with thorns:} \\
+{\tt CactusElliptic/EllTest},\\
+ {\tt CactusWave/IDScalarWaveElliptic}
 
 \end{itemize}
 
-\subsection{Using EllBase}
+\section{ToDo}
+\begin{itemize}
+\item{}Put more equation classes into {\tt EllBase}
+\item{}To way of passing  boundary conditions  into the 
+elliptic solvers has not fully consolidated. We have some good ideas
+on what the interface should look like, but the implementation will
+take some time. If you are worried about BCs, please contact me.
+\end{itemize}
+
+\section{Using the elliptic calling interface}
+EllBase provides a calling interfaces for each of the elliptic classes 
+implemented.
+As a user you provide the necessary information needed by a solver
+for that particular elliptic class, in general:
+\begin{itemize}
+\item{} you provide information on the metric
+\item{} you provide the gridfunction to solve for, 
+\item{} you pass the coefficient matrix, the source terms.
+\item{} you set arrays containing information on tolerances.
+\item{} you can now chose a solver, which has to be registered 
+for that elliptic class. 
+\item{\bf Motivation:} At a later stage you  might want to compile with a different 
+solver for this elliptic class: just change the name of the solver in your
+elliptic interface call. If somebody improves a solver you have been using,
+there is no need for you to change any code on your side: the interface 
+will hide all of that. Another advantage is that your code will compile 
+and run, even though certain solvers are not compiled in. In these case, you 
+will have to do some return value checking to offer alternatives.
+\end{itemize}
+
+\subsection{\tt Ell\_LinFlat}
+To call this interface from {\bf Fortran}:
+\begin{verbatim}
+	 call Ell_LinFlatSolver(ierr, cctkGH, phi_gfi, M_gfi, N_gfi,
+	.                       AbsTol, RelTol, "solvername") 
+\end{verbatim}
+To call this interface from {\bf C}:
+\begin{verbatim}
+
+	 ierr = Ell_LinFlatSolver(GH, phi_gfi, M_gfi, N_gfi,
+	                          AbsTol, RelTol, "solvername"); 
+\end{verbatim}
+{\bf Argument List:}
+\begin{itemize}
+\item{\tt ierr}: return value: ``0'' success
+\item{\tt cctkGH}: the Fortran ``pointer'' to the grid function
+hierachy.
+\item{\tt GH}: the C pointer to the grid hierarchy, type: {\tt pGH *GH}
+\item{\tt phi\_gif}: the integer {\em index} of the grid function so solver
+for.
+\item{\tt M\_gfi}:  the integer {\em index} of the grid function which holds
+$M$.
+\item{\tt N\_gif}: the integer {\em index} of the grid function which holds $N$
+\item{\tt AbsTol}: array of size $3$: holding {\em absolute} tolerance values for the 
+$L_1$, $L_2$, $L_\infty$ Norm.  Check, if the solver side supports
+these norms.The interface side does not guarantee that these norms are 
+actually implemenented by a solver. See the section on Norms: \ref{sec:ellnorms}.
+\item{\tt RelTol}: array of size $3$: holding {\em relative}
+tolerance factors for the $L_1$, $L_2$, $L_\infty$. Check, if the 
+solver side supports these norms. The interface side does not
+guarantee that these norms are actually implemenented by a solver. 
+See the section on Norms: \ref{sec:ellnorms}.
+\item{\tt  "solvername"}: the name of a solver, which is registered
+for a particular equation class. How to find out the names ? Either
+check the documentation of the elliptic solvers or check for
+registration infomation outputted by a cactus at runtime.
+\end{itemize}
+{\bf Example use in Fortran}, as used in the WaveToy arrangement: {\tt
+./WavToy/IDScalarWave}:
+\begin{verbatim}
+
+c     We derive the grid function indeces from the names of the 
+c     grid functions:
+      call CCTK_VarIndex (Mcoeff_gfi, "idscalarwaveelliptic::Mcoeff")
+      call CCTK_VarIndex (Ncoeff_gfi, "idscalarwaveelliptic::Ncoeff")
+      call CCTK_VarIndex (phi_gfi,    "wavetoy::phi")
+
+c     Load the Absolute Tolerance Arrays
+      AbsTol(1)=1.0d-5
+      AbsTol(2)=1.0d-5
+      AbsTol(3)=1.0d-5
+
+c     Load the Relative Tolerance Arrays, they are not
+c     used here: -1
+      RelTol(1)=-1
+      RelTol(2)=-1
+      RelTol(3)=-1
+
+c     Call to elliptic solver, named ``sor''
+      call Ell_LinFlatSolver(ierr, cctkGH, 
+     .     phi_gfi, Mcoeff_gfi, Ncoeff_gfi, AbsTol, RelTol,
+     .     "sor")
+
+c     Do some error checking, a call to another solver 
+c     could be coded here
+      if (ierr.ne.0) then
+         call CCTK_WARN(0,"Requested solver not found / solve failed");
+      endif
+\end{verbatim}
+
+
+\subsection{\tt Ell\_LinMetric}
+To call this interface from {\bf Fortran}:
+\begin{verbatim}
+	 call Ell_LinMetricSolver(ierr, cctkGH, Metric_gfi, 
+	.	 	          phi_gfi, M_gfi, N_gfi,
+	.                         AbsTol, RelTol, "solvername") 
+\end{verbatim}
+To call this interface from {\bf C}:
+\begin{verbatim}
+	 ierr = Ell_LinMetricSolver(GH, Metric_gfi, 
+		 	            phi_gfi, M_gfi, N_gfi,
+	                            AbsTol, RelTol, "solvername");
+\end{verbatim}
+{\bf Argument List:}
+\begin{itemize}
+\item{\tt ierr}: return value: ``0'' success
+\item{\tt cctkGH}: the Fortran ``pointer'' to the grid function
+hierachy.
+\item{\tt GH}: the C pointer to the grid hierarchy, type: {\tt pGH
+*GH}
+\item{\tt Metric\_gfi}: array of size $6$, containing the {\em index} components of 
+the metric $g$: $g_{11}$, $g_{12}$, $g_{13}$, $g_{22}$, $g_{23}$,
+$g_{33}$. The {\bf order} is important.
+\item{\tt phi\_gif}: the integer {\em index} of the grid function so solver
+for.
+\item{\tt M\_gfi}:  the integer {\em index} of the grid function which holds
+$M$.
+\item{\tt N\_gif}: the integer {\em index} of the grid function which holds $N$
+\item{\tt AbsTol}: array of size $3$: holding {\em absolute} tolerance values for the 
+$L_1$, $L_2$, $L_\infty$ Norm.  Check, if the solver side supports
+these norms.The interface side does not guarantee that these norms are 
+actually implemenented by a solver. See the section on Norms: \ref{sec:ellnorms}.
+\item{\tt RelTol}: array of size $3$: holding {\em relative}
+tolerance factors for the $L_1$, $L_2$, $L_\infty$. Check, if the 
+solver side supports these norms. The interface side does not
+guarantee that these norms are actually implemenented by a solver. 
+See the section on Norms: \ref{sec:ellnorms}.
+\item{\tt  "solvername"}: the name of a solver, which is registered
+for a particular equation class. How to find out the names ? Either
+check the documentation of the elliptic solvers or check for
+registration infomation outputted by a cactus at runtime.
+\end{itemize}
+
+\subsection{\tt Ell\_LinConfMetric}
+To call this interface from {\bf Fortran}:
+\begin{verbatim}
+	 call Ell_LinMetricSolver(ierr, cctkGH, MetricPsi_gfi, 
+	.	 	          phi_gfi, M_gfi, N_gfi,
+	.                         AbsTol, RelTol, "solvername") 
+\end{verbatim}
+To call this interface from {\bf C}:
+\begin{verbatim}
+	 ierr = Ell_LinMetricSolver(GH, MetricPsi_gfi, 
+		 	            phi_gfi, M_gfi, N_gfi,
+	                            AbsTol, RelTol, "solvername");
+\end{verbatim}
+{\bf Argument List:}
+\begin{itemize}
+\item{\tt ierr}: return value: ``0'' success
+\item{\tt cctkGH}: the Fortran ``pointer'' to the grid function
+hierachy.
+\item{\tt GH}: the C pointer to the grid hierarchy, type: {\tt pGH
+*GH}
+\item{\tt MetricPsi\_gfi}: array of size $7$, containing the {\em
+grid function index} of the metric components and the {\em grid
+function index} of the conformal factor $\Psi$: $g_{11}$, 
+$g_{12}$, $g_{13}$, $g_{22}$, $g_{23}$, $g_{33}$, $\Psi$. The {\bf order} is important.
+\item{\tt phi\_gif}: the integer {\em index} of the grid function so solver
+for.
+\item{\tt M\_gfi}:  the integer {\em index} of the grid function which holds
+$M$.
+\item{\tt N\_gif}: the integer {\em index} of the grid function which holds $N$
+\item{\tt AbsTol}: array of size $3$: holding {\em absolute} tolerance values for the 
+$L_1$, $L_2$, $L_\infty$ Norm.  Check, if the solver side supports
+these norms.The interface side does not guarantee that these norms are 
+actually implemenented by a solver. See the section on Norms: \ref{sec:ellnorms}.
+\item{\tt RelTol}: array of size $3$: holding {\em relative}
+tolerance factors for the $L_1$, $L_2$, $L_\infty$. Check, if the 
+solver side supports these norms. The interface side does not
+guarantee that these norms are actually implemenented by a solver. 
+See the section on Norms: \ref{sec:ellnorms}.
+\item{\tt  "solvername"}: the name of a solver, which is registered
+for a particular equation class. How to find out the names ? Either
+check the documentation of the elliptic solvers or check for
+registration infomation outputted by a cactus at runtime.
+
+\end{itemize}
+
+
+
+\section{Extending the elliptic solver class}
 
 EllBase by itself does not provide any elliptic solving capabilities. 
 It merely provides the registration structure and calling interface.
@@ -56,31 +256,21 @@ The idea of a unified calling interface can be motivated as follows:
 assume you a have elliptic problem which conforms to one of the elliptic 
 classes defined in EllBase.
 
-In your routine you provide the necessay information needed by a solver
-for that particular elliptic class: you provide the function to solve for, 
-the coefficient matrix, etc. You can now chose a solver, which is registered 
-for that elliptic class. Later you  might want to compile with a different 
-solver for this elliptic class: just change the name of the solver in your
-elliptic interface call. If somebody improves a solver you have been using,
-there is no need for you to change any code on your side: the interface 
-will hide all of that. Another advantage is that your code will compile 
-and run, even though certain solvers are not compiled in. In these case, you 
-will have to do some return value checking to offer alterntives.
 
-\subsubsection{Registration Mechanism}
+\subsection{Registration Mechanism}
 
 Before a user can successfully apply a elliptic solver to one of his problems,
-two things need to be done by the author who programms the solver.
+two things need to be done by the author who programs the solver.
 \begin{itemize}
 \item{\bf Register a class of elliptic equations} Depending on the elliptic 
 problem This provides the unique calling, the solving routines needs to have 
 specific input data. The interface, which is called by the user, has to 
 reflect these arguments. EllBase already offers 
-serveral of these interfaces, but if you need to have a new one, you can 
+several of these interfaces, but if you need to have a new one, you can 
 provide your own.
 
-\item{\bf Register a solver for a particular elliptic equation classe}
-Once a class of ellitpic equations has been made available as described 
+\item{\bf Register a solver for a particular elliptic equation class}
+Once a class of elliptic equations has been made available as described 
 above, the author can now register solvers for that particular class. 
 Later a user will access the solver calling the interface with the 
 arguments needed for the elliptic class and a name, under which a solver 
@@ -95,9 +285,9 @@ and/or an elliptic solver at STARTUP (see \ref{sec:RFR} for information on
 sure, that the elliptic class is registered {\em before} the solver 
 registration takes place. 
 
-\subsubsection{EllBase Programming Guide}
+\subsection{EllBase Programming Guide}
 
-Here we give a step by step guide on how to implement an new elliptiv 
+Here we give a step by step guide on how to implement an new elliptic 
 solver class, its interface and provide a solver for this class.  Since 
 some of the functionality needed in the registration code can only be 
 achieved in C, a basic knowledge of C is helpful.
@@ -114,7 +304,7 @@ takes the coefficient matrix $M$:
 %\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 
+``{\tt ThornFastSOR}''. Since I will only demonstrate the registration principle 
 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}''
@@ -145,7 +335,7 @@ void Ell_SimpleEllSolverRegistry(void (*solver_func), const char *solver_name)
 \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
-SimpleEllSolverDB}. This database is declared in statment {\tt static pNamedData...}.
+SimpleEllSolverDB}. This database is declared in statement {\tt static pNamedData...}.
 
 
 Next, we write our interface in the same file {\tt ./SimpleEll\_Interface.c}:
@@ -181,7 +371,7 @@ To allow calls from Fortran, the interface in C needs to be ``wrapped''.
 accessible by the elliptic registry).
 
 \begin{verbatim}
-/* Fortran wrappr for the routine Ell_SimpleEllSolver */
+/* Fortran wrapper for the routine Ell_SimpleEllSolver */
 void FMODIFIER FORTRAN_NAME(Ell_SimpelEllSolver)
      (cGH *GH, int *FieldIndex, int *MIndex, 
      int *AbsTol, int *RelTol, ONE_FORTSTRING_ARG) {
@@ -230,7 +420,7 @@ This Fortran solver receives the following arguments: the ``typical''
 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 
+In the declaration section, we declare: 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}.
 
@@ -270,12 +460,12 @@ 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 
+In the body of the program 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.)
- To make this information of a possibly empty matrix available to Fortran, we load a 3-dim. and pass this array thorugh to Fortran. See discussion above.
+ To make this information of a possibly empty matrix available to Fortran, we load a 3-dim. and pass this array through to Fortran. See discussion above.
 
 
 \item{\bf Elliptic solver startup}: {\tt ./src/Startup.c}\\
@@ -300,7 +490,7 @@ 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, 
+We schedule the registration of the fast SOR solver at CCTK\_BASE, by this time, 
 {\em the elliptic class} {\tt Ell\_SimpleEll} has already been registered. 
 \begin{verbatim}
 schedule FastSOR_register at CCTK_INITIAL
@@ -309,7 +499,6 @@ schedule FastSOR_register at CCTK_INITIAL
 } ``Register the fast sor solver''
 \end{verbatim}
 
-
 \end{itemize}
 
 \end{document}