Additional documentation. Update with the table_handle interface.

git-svn-id: https://svn.cct.lsu.edu/repos/numrel/LSUThorns/SummationByParts/trunk@30 f69c4107-0314-4c4f-9ad4-17e986b73f4a

1 files changed, 90 insertions, 12 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 1e23fc3..ecc0042 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -176,7 +176,7 @@ restricted full norm 4-3 operators.
 In the diagonal case the 2-1 and 4-3 operators are unique whereas the 6-3
 and 8-4 operators have 1 and 3 free parameters, respectively. In the restricted
 full norm case the 4-3 operators have 3 free parameters and the 6-5 operators
-have 4, while in the full norm case the number of free parameters are 1 less
+have 4, while in the full norm case the number of free parameters is 1 less
 than the restricted full case.
 \section{Numerical Implementation}
 Currently this thorn implements only diagonal and restricted full norm SBP
@@ -201,7 +201,8 @@ performed by a set of aliased functions. In this way things are kept flexible
 in the sense that different thorns each can provide their own way of
 calculating derivatives but if they use the same calling interface the
 user can switch between different derivative schemes by simply activating
-the appropriate finite differencing thorn.
+the appropriate finite differencing thorn. Also the same derivative routines
+can be called from both C and Fortran.
 
 There are currently two different calling interfaces corresponding to different
 levels of flexibility. In the first case the fact that derivatives are
@@ -226,9 +227,17 @@ works on whole grid functions you have to add:
 SUBROUTINE Diff_gv ( CCTK_POINTER_TO_CONST IN cctkGH, \
                      CCTK_INT IN dir, \
                      CCTK_REAL IN ARRAY var, \
-                     CCTK_REAL OUT ARRAY dvar )
+                     CCTK_REAL OUT ARRAY dvar, \
+                     CCTK_INT IN table_handle )
 USES FUNCTION Diff_gv
 \end{verbatim}
+Here {\tt cctkGH} is the pointer to the cactus GH, {\tt dir} is the direction
+of the derivative (0 for $x$, 1 for $y$ and 2 for $z$), {\tt var} is the grid
+function to calculate derivatives of and {\tt dvar} is the grid function where
+the derivative is to be stored and {\tt table\_handle} is an integer that
+contains a handle for a keyword table with optional parameters. If there are
+no optional paramters just pass in a negative value.
+
 To use the interface that returns the finite difference coefficients you have 
 to add:
 \begin{verbatim}
@@ -240,22 +249,91 @@ SUBROUTINE Diff_coeff ( CCTK_POINTER_TO_CONST IN cctkGH, \
                         CCTK_REAL OUT ARRAY q, \
                         CCTK_INT IN table_handle )
 \end{verbatim}
-\subsection{Special Behaviour}
+Here, again, {\tt cctkGH} is the pointer to the cactus GH, {\tt dir} is the
+direction of the derivative, {\tt nsize} is the grid size in the direction
+you are interested in, {\tt imin} and {\tt imax} are 1D integer arrays of size
+{\tt nsize} that on return will contain the minimum and maximum index of the
+stencil in direction {\tt dir}, {\tt q} is a 2D real array of size 
+{\tt nsize}$\times${\tt nsize} that on return will contain the coefficients
+for the derivatives. The {\tt table\_handle} serves the same purpose as in
+the previous case.
 
-\subsection{Interaction With Other Thorns}
+%\subsection{Special Behaviour}
 
-\subsection{Examples}
+%\subsection{Interaction With Other Thorns}
 
+\subsection{Examples}
+The following piece of Fortran code, shows how to calculate derivatives of
+a grid function, f, and store the derivatives in the x-, y- and z-directions
+in the grid functions  dxf, dyf and dzf:
+\begin{verbatim}
+  call Diff_gv (cctkGH, 0, f, dxf, -1)
+  call Diff_gv (cctkGH, 1, f, dyf, -1)
+  call Diff_gv (cctkGH, 2, f, dzf, -1)
+\end{verbatim}
+In order to use the interface for doing the pointwise derivatives, the
+following Fortran90 example shows the necessary declarations and an example
+of how to calculate the derivatives:
+\begin{verbatim}
+  CCTK_REAL, dimension(:,:), allocatable :: qx, qy, qz
+  CCTK_INT, dimension(:), allocatable :: iminx, imaxx, iminy, &
+                                         imaxy, iminz, imaxz
+  CCTK_REAL :: idelx, idely, idelz
+  CCTK_INT :: i, j, k
+
+  allocate ( qx(cctk_lsh(1),cctk_lsh(1)), &
+             qy(cctk_lsh(2),cctk_lsh(2)), &
+             qz(cctk_lsh(3),cctk_lsh(3)), &
+             iminx(cctk_lsh(1)), imaxx(cctk_lsh(1)), &
+             iminy(cctk_lsh(2)), imaxy(cctk_lsh(2)), &
+             iminz(cctk_lsh(3)), imaxz(cctk_lsh(3)) )
+
+  call Diff_Coeff ( cctkGH, 0, cctk_lsh(1), iminx, imaxx, qx, -1 )
+  call Diff_Coeff ( cctkGH, 1, cctk_lsh(2), iminy, imaxy, qy, -1 )
+  call Diff_Coeff ( cctkGH, 2, cctk_lsh(3), iminz, imaxz, qz, -1 )
+
+  idelx = 1.0d0 / CCTK_DELTA_SPACE(1)
+  idely = 1.0d0 / CCTK_DELTA_SPACE(2)
+  idelz = 1.0d0 / CCTK_DELTA_SPACE(3)
+
+  do k = 1, cctk_lsh(3)
+    do j = 1, cctk_lsh(2)
+      do i = 1, cctk_lsh(1)
+        dxf(i,j,k) = idelx * sum ( qx(iminx(i):imaxx(i),i) * &
+                                     f(iminx(i):imaxx(i),j,k) )
+        dyf(i,j,k) = idely * sum ( qy(iminy(j):imaxy(j),j) * &
+                                     f(i,iminy(j):imaxy(j),k) )
+        dzf(i,j,k) = idelz * sum ( qz(iminz(k):imaxz(k),k) * &
+                                     f(i,j,iminz(k):imaxz(k)) )
+
+      end do
+    end do
+  end do
+
+  deallocate ( qx, qy, qz, iminx, imaxx, iminy, imaxy, iminz, imaxz )
+\end{verbatim}
 \subsection{Support and Feedback}
+This thorn is maintained by Peter Diener. Any questions and comments should
+be directed by e-mail to diener@cct.lsu.edu.
 
 \section{History}
+This thorn grew out of the needs of a multipatch relativity code and as
+such was initially designed to those needs. The addition of the possibility
+of passing in a handle for a keyword table was done at the request of
+Jonathan Thornburg and should make it easy to extend the thorn with
+additional features. The addition of the coefficient interface was done
+at the request of Bela Szilagyi who felt that the storage overhead was
+to large for his code. In the near future the thorn will be extended with
+second derivatives SBP operators.
+
+%\subsection{Thorn Source Code}
+%
+%\subsection{Thorn Documentation}
 
-\subsection{Thorn Source Code}
-
-\subsection{Thorn Documentation}
-
-\subsection{Acknowledgements}
-
+\section{Acknowledgements}
+We thank Jos\'{e} M.\ Mart\'{\i}n-Garc\'{\i}a for very kindly providing us
+with a very well designed mathematica script to calculate the finite
+difference and scalar product coefficients.
 
 \begin{thebibliography}{9}
 \bibitem{strand93} Bo Strand, 1994, Journal of Computational Physics, 110,