Document the generic table method.

git-svn-id: http://svn.cactuscode.org/arrangements/CactusNumerical/MoL/trunk@31 578cdeb0-5ea1-4b81-8215-5a3b8777ee0b

1 files changed, 62 insertions, 0 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 9e61b6c..7274602 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -419,6 +419,68 @@ MoL thorn and the flesh. Also the synchronization of grids across
 separate processors will be dealt with by the MoL thorn, the driver
 the flesh.
 
+\subsection{Evolution method writers}
+\label{AlphaThorns_MoL_sec:evol-meth-writ}
+
+If you want to try adding a new evolution method to MoL the simplest
+way is to use the generic table option to specify it completely in the
+parameter file - no coding is required at all.
+
+All the generic methods evolve the equation
+\begin{equation}
+  \label{AlphaThorns_MoL_eq:mol3}
+  \partial_t {\bf q} = {\bf L}({\bf q})
+\end{equation}
+using the following algorithm for an $N$-step method:
+\begin{eqnarray}
+  \label{AlphaThorns_MoL_eq:genrk1}
+  {\bf q}^{(0)} & = & {\bf q}^n, \nonumber \\
+  {\bf q}^{(i)} & = & \sum_{k=0}^{i-1} \left( \alpha_{ik} {\bf
+  q}^{(k)} \right) + \Delta t \beta_{i-1} {\bf L} ( {\bf q}^{(i-1)} ),
+  \qquad i = 1, \dots, N, \\
+  {\bf q}^{n+1} & = & {\bf q}^{(N)}. \nonumber
+\end{eqnarray}
+This method is completely specified by $N$ ({\tt
+  GenericIntermediateSteps}) and the $\alpha$ ({\tt
+  GenericAlphaCoeffs}) and $\beta$ ({\tt GenericBetaCoeffs})
+arrays. The names in parentheses give the keys in a table that MoL
+will use. This table is created from the string parameter {\tt
+  Generic\_Method\_Descriptor}. 
+
+As an example, the standard TVD RK2 method that is implemented both in
+optimized and generic form is written as
+\begin{eqnarray}
+  \label{AlphaThorns_MoL_eq:rk2}
+  {\bf q}^{(1)} & = & {\bf q}^n + \Delta t {\bf L} ({\bf q}^n), \\
+  {\bf q}^{n+1} & = & \frac{1}{2} \left( {\bf q}^n + {\bf q}^{(1)} +
+  \Delta t {\bf L} ({\bf q}^{(1)}) \right). 
+\end{eqnarray}
+To implement this using the generic table options, use
+\begin{verbatim}
+methodoflines::MoL_Intermediate_Steps = 2
+methodoflines::MoL_Num_Scratch_Levels = 1
+methodoflines::Generic_Method_Descriptor = \
+           "GenericIntermediateSteps = 2 \
+            GenericAlphaCoeffs = { 1.0 0.0 0.5 0.5 } \
+            GenericBetaCoeffs = { 1.0 0.5 }"
+\end{verbatim}
+The number of steps specified in the table must be the same as {\tt
+  MoL\_Intermediate\_Steps}, and the number of scratch levels should
+be at least {\tt MoL\_Intermediate\_Steps - 1}.
+
+The generic methods are somewhat inefficient for use in production
+runs, so it is frequently better to write an optimized version once
+you are happy with the method. To do this you should
+\begin{itemize}
+\item write your code into a new file, called from the scheduler under
+  the alias {\tt MoL\_Add},
+\item make certain that at each intermediate step the correct values
+  of {\tt cctk\_time} and {\tt cctk\_delta\_time} are set in {\tt
+    SetTime.c} for mesh refinement, boundary conditions and so on,
+\item make certain that you check for the number of intermediate steps
+  in {\tt ParamCheck.c}.
+\end{itemize}
+
 \section{Example}
 \label{AlphaThorns_MoL_sec:example}