Added some documentation.

git-svn-id: http://svn.cactuscode.org/arrangements/CactusNumerical/Cartoon2D/trunk@28 eec4d7dc-71c2-46d6-addf-10296150bf52

3 files changed, 536 insertions, 0 deletions

diff --git a/doc/cartoon_plane.eps b/doc/cartoon_plane.eps
new file mode 100644
index 0000000..a8d1c1b
--- /dev/null
+++ b/doc/cartoon_plane.eps
@@ -0,0 +1,171 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: cartoon_plane.eps
+%%Creator: fig2dev Version 3.2 Patchlevel 3d
+%%CreationDate: Tue Apr 16 23:04:34 2002
+%%For: dp@nbdell15 (Denis Pollney,,,)
+%%BoundingBox: 0 0 239 491
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 491 moveto 0 0 lineto 239 0 lineto 239 491 lineto closepath clip newpath
+-112.6 518.7 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+%
+% Fig objects follow
+%
+% Polyline
+7.500 slw
+n 2250 1125 m 4275 3150 l 4275 7650 l 2250 5625 l 2250 1125 l
+ cp gs col6 0.70 shd ef gr gs col0 s gr 
+% Polyline
+n 2700 1125 m 2925 1125 l 4950 3150 l 4725 3150 l 2700 1125 l
+ cp gs col0 s gr 
+% Polyline
+n 3825 3150 m 4050 3150 l 4050 7650 l 3825 7650 l
+ cp gs col0 s gr 
+% Polyline
+n 4050 3150 m 4275 3150 l 4275 7650 l 4050 7650 l
+ cp gs col0 s gr 
+% Polyline
+n 4500 3150 m 4725 3150 l 4725 7650 l 4500 7650 l
+ cp gs col0 s gr 
+% Polyline
+n 4725 3150 m 4950 3150 l 4950 7650 l 4725 7650 l
+ cp gs col0 s gr 
+% Polyline
+n 1800 1125 m 3825 3150 l 3825 7650 l 1800 5625 l 1800 1125 l
+ cp gs col0 s gr 
+% Polyline
+n 1800 1125 m 2025 1125 l 4050 3150 l 3825 3150 l 1800 1125 l
+ cp gs col0 s gr 
+% Polyline
+n 2025 1125 m 2250 1125 l 4275 3150 l 4050 3150 l 2025 1125 l
+ cp gs col0 s gr 
+% Polyline
+n 2475 1125 m 2700 1125 l 4725 3150 l 4500 3150 l 2475 1125 l
+ cp gs col0 s gr 
+% Polyline
+n 2250 1125 m 2475 1125 l 4500 3150 l 4275 3150 l 2250 1125 l
+ cp gs col6 1.00 shd ef gr gs col0 s gr 
+% Polyline
+n 4275 3150 m 4500 3150 l 4500 7650 l 4275 7650 l
+ cp gs col6 1.00 shd ef gr gs col0 s gr 
+% Polyline
+n 2025 1125 m 4050 3150 l 4050 7650 l 2025 5625 l 2025 1125 l
+ cp gs col0 s gr 
+% Polyline
+15.000 slw
+gs  clippath
+2445 660 m 2325 660 l 2325 947 l 2385 707 l 2445 947 l cp
+eoclip
+n 2385 1125 m
+ 2385 675 l gs col0 s gr gr
+
+% arrowhead
+n 2445 947 m 2385 707 l 2325 947 l 2445 947 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+gs  clippath
+4828 8153 m 4913 8068 l 4709 7864 l 4837 8077 l 4624 7949 l cp
+eoclip
+n 4410 7650 m
+ 4860 8100 l gs col0 s gr gr
+
+% arrowhead
+n 4624 7949 m 4837 8077 l 4709 7864 l 4624 7949 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+gs  clippath
+5280 5685 m 5280 5565 l 4993 5565 l 5233 5625 l 4993 5685 l cp
+eoclip
+n 4545 5625 m
+ 5265 5625 l gs col0 s gr gr
+
+% arrowhead
+n 4993 5685 m 5233 5625 l 4993 5565 l 4993 5685 l  cp gs 0.00 setgray ef gr  col0 s
+/Times-Roman ff 270.00 scf sf
+5445 5715 m
+gs 1 -1 sc (y) col0 sh gr
+/Times-Roman ff 270.00 scf sf
+4905 8235 m
+gs 1 -1 sc (x) col0 sh gr
+/Times-Roman ff 270.00 scf sf
+2340 585 m
+gs 1 -1 sc (z) col0 sh gr
+$F2psEnd
+rs
diff --git a/doc/cartoon_plane.fig b/doc/cartoon_plane.fig
new file mode 100644
index 0000000..727019d
--- /dev/null
+++ b/doc/cartoon_plane.fig
@@ -0,0 +1,47 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 6
+	 2700 1125 2925 1125 4950 3150 4725 3150 2700 1125 2700 1125
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 3825 3150 4050 3150 4050 7650 3825 7650 3825 3150
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 4050 3150 4275 3150 4275 7650 4050 7650 4050 3150
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 4500 3150 4725 3150 4725 7650 4500 7650 4500 3150
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 4725 3150 4950 3150 4950 7650 4725 7650 4725 3150
+2 3 0 1 0 3 50 0 -1 0.000 0 0 -1 0 0 6
+	 1800 1125 3825 3150 3825 7650 1800 5625 1800 1125 1800 1125
+2 3 0 1 0 3 50 0 -1 0.000 0 0 -1 0 0 6
+	 1800 1125 2025 1125 4050 3150 3825 3150 1800 1125 1800 1125
+2 3 0 1 0 3 50 0 -1 0.000 0 0 -1 0 0 6
+	 2025 1125 2250 1125 4275 3150 4050 3150 2025 1125 2025 1125
+2 3 0 1 0 3 50 0 -1 0.000 0 0 -1 0 0 6
+	 2475 1125 2700 1125 4725 3150 4500 3150 2475 1125 2475 1125
+2 3 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 6
+	 2250 1125 2475 1125 4500 3150 4275 3150 2250 1125 2250 1125
+2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5
+	 4275 3150 4500 3150 4500 7650 4275 7650 4275 3150
+2 3 0 1 0 3 50 0 -1 0.000 0 0 -1 0 0 6
+	 2025 1125 4050 3150 4050 7650 2025 5625 2025 1125 2025 1125
+2 3 0 1 0 6 60 0 14 0.000 0 0 -1 0 0 6
+	 2250 1125 4275 3150 4275 7650 2250 5625 2250 1125 2250 1125
+2 1 0 2 0 7 50 0 -1 0.000 0 0 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 2385 1125 2385 675
+2 1 0 2 0 7 50 0 -1 0.000 0 0 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 4410 7650 4860 8100
+2 1 0 2 0 7 50 0 -1 0.000 0 0 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 4545 5625 5265 5625
+4 0 0 50 0 0 18 0.0000 4 195 120 5445 5715 y\001
+4 0 0 50 0 0 18 0.0000 4 135 135 4905 8235 x\001
+4 0 0 50 0 0 18 0.0000 4 135 120 2340 585 z\001
diff --git a/doc/documentation.tex b/doc/documentation.tex
new file mode 100644
index 0000000..61fe9fd
--- /dev/null
+++ b/doc/documentation.tex
@@ -0,0 +1,318 @@
+% /*@@
+%   @file      documentation.tex
+%   @date      16 April 2002
+%   @author    Denis Pollney
+%   @desc 
+%              Cartoon2D user/maintainer guide.
+%   @enddesc 
+%   @version $Header$      
+% @@*/
+\documentclass{article}
+\usepackage{epsfig}
+
+\parskip = 0 pt
+\parindent = 0pt
+\oddsidemargin = 0 cm
+\textwidth = 16 cm
+\topmargin = -1 cm
+\textheight = 24 cm
+
+\begin{document}
+\title{Using Cartoon2D}
+\author{Denis Pollney}
+\date{April 2002}
+
+\maketitle
+
+\abstract{
+  The \texttt{Cartoon2D} thorn allows fully 3D codes to be used
+  to model axisymmetric systems, by considering a 3D evolution which
+  is only one plane thick and applying a rotational tensor
+  transformation to the flat faces of the plane as a boundary
+  condition. This allows 3D codes to be tested efficiently on 2D
+  problems, as well as providing a means of carrying out axisymmetric
+  evolutions in cartesian coordinates without problems at the axis.
+}
+
+\section{Background}
+
+The \texttt{Cartoon2D} thorn is the implementation of an idea first
+presented in \cite{Alcubierre-etal-2001}. The principle is to use a
+3-dimensional Cartesian $(x,y,z)$ coordinate grid which covers the
+$y=0$ plane, but is only one finite difference molecule in width in
+the $y$-direction. The field variables in the $y=0$ plane can be
+updated using standard 3D $(x,y,z)$ coordinate finite differencing,
+with off-plane derivatives calculated by performing appropriate
+rotations of field variables using the axisymmetic assumption.
+This technique has the advantage of removing a number of the axis
+problems normally associated with axisymmetric codes.
+
+The `cartoon' method was first implemented in Cactus3 by Steve Brandt
+and Bernd Br\"ugmann, and was translated to Cactus4 by Sai
+Iyer. Details of the method can be found in
+\cite{Alcubierre-etal-2001}. This document provides a practical guide
+to using the code as it is currently implemented.
+
+\section{Basic usage}
+
+Only a small number of parameters need to be set to use
+\texttt{Cartoon2D}.
+
+\begin{description}
+
+  \item[\texttt{cartoon\_active}] A flag which determines whether or
+  not the cartoon boundary condition should be applied. This should be
+  set to ``yes'' to use \texttt{Cartoon2D}, otherwise the evolution
+  will be assumed to be standard 3D.
+
+  \item[\texttt{order}] Determines the order of interpolations to be
+  carried out. This will determine the number of ghost zones that you
+  need to specify in the $y$-direction.
+
+  \item[\texttt{allow\_grid\_resize}] When this flag is set to
+  ``yes'', \texttt{Cartoon2D} is allowed to modify the grid sizes
+  specified in the parameter file so that a cartoon-compatible grid is
+  used. See below.
+
+  \item[\texttt{verbose}] Causes \texttt{Cartoon2D} to print a lot of
+  messages.
+
+%
+% FIXME: The param.ccl file also mentions a stencil parameter, which
+% seems not to be used in the code.
+%
+
+\end{description}
+
+For example, the following is a section of a parameter file which sets
+up a cartoon-style grid in bitant mode.
+
+\begin{verbatim}
+
+activethorns = "cartoon2d"
+
+cartoon2d::cartoon_active		= "yes"
+cartoon2d::order                	= 3
+cartoon2d::allow_grid_resize		= "yes"
+
+grid::type                              = "byspacing"
+grid::domain				= "bitant"
+grid::bitant_plane			= "xy"
+grid::dxyz                              = 0.2
+
+driver::global_nx                       = 16
+driver::global_ny                       = 3
+driver::global_nz                       = 16
+
+driver::ghost_size_x                    = 2
+driver::ghost_size_y                    = 1
+driver::ghost_size_z                    = 2
+
+driver::processor_topology       	= "manual"
+driver::processor_topology_3d_x  	= 1
+driver::processor_topology_3d_y  	= 1
+driver::processor_topology_3d_z  	= 2
+
+grid::avoid_originy                     = "yes"
+
+\end{verbatim}
+
+The following features are of note:
+
+\begin{itemize}
+
+  \item The \texttt{order} parameter specifies that 3rd order
+  interpolation is to be used. This requires that only one ghost zone
+  is required in the y direction (\texttt{ghost\_size\_y}). If 4th
+  order interpolation was specified, then two ghost zones would be
+  required.
+
+  \item The \texttt{allow\_grid\_resize} flag has been set, allowing
+  \texttt{Cartoon2D} to modify the grid appropriately so that, for
+  instance, it only extends a given number of ghost zones beyond the
+  $z$-axis.
+
+  \item The bitant plane should always be ``\texttt{xy}'', which means
+  that only the positive $z$-axis is evolved and a reflection boundary
+  is imposed along $z=0$.
+
+  \item It is not necessary, but often helpful, to specify the
+  processor topology explicitly to ensure that that only one processor
+  is allocated to the $y$ direction, and that the processors in the
+  $x$ and $z$ directions reflect the relative lengths of these axes
+  (though in this example it doesn't matter which of these axes gets
+  two processors).
+
+  \item The \texttt{avoid\_originy} parameter needs to be set so that
+    the cartoon plane corresponds to $y=0$.
+
+\end{itemize}
+
+Also, it is important to keep in mind that other thorns may also
+require their own parameters to be set in order to interact
+appropriately with \texttt{Cartoon2D}. For instance, see 
+Section \ref{sec:interaction}.
+
+Working parameter files can be found in the \texttt{Cartoon2D/test/}
+directory.
+
+\begin{figure}
+  \centering
+  \epsfig{file=cartoon_plane.eps, height=80mm}
+  \caption{The cartoon plane layout. The symmetry axis is the
+    $z$-axis, with grid functions defined on the $y=0$ plane, in this
+    example with two ghost zones.}
+\end{figure}
+
+\section{Automatic grid re-sizing}
+\label{sec:regrid}
+
+The \texttt{Cartoon2D} thorn has some non-standard requirements of the
+grid which is normally set up by the \texttt{grid} implementation (for
+instance, by \texttt{CartGrid3D}). In particular,
+
+\begin{itemize}
+
+  \item the grid in the $y$ direction should be exactly one plane in
+    width, plus twice the number of $y$ ghost zones.
+
+  \item the grid in the $x$ direction only needs to extend to the
+    $z$-axis, plus a few extra hang-overs. The number of extra points
+    is determined by the number of $y$ ghost zone points.
+
+\end{itemize}
+
+These requirements (in particular the second) can not be met if the
+grid is specified \texttt{byspacing} (ie. by giving a $dx$ value),
+since in this case the grid is set up assuming that the axes should be
+centred in each grid direction.
+
+One way to get around this is to specify the grid \texttt{byrange},
+giving minimum and maximum coordinate values for each axis so that the
+$(dx,dy,dz)$ values are determined by dividing the range by the number
+of grid points. In this it can, however, be quite complicated to
+ensure that the grid spacing is even in each direction and that an
+appropriate number of ghost points extend past the $z$ axis.
+
+A simple hack to get around this complication is to specify the grid
+\texttt{byspacing}, but to set the \texttt{allow\_grid\_resize}
+parameter. In this case, the $(dx,dy,dz)$ values can be set in the
+parameter file, and the grid ranges will be calculated based on the
+above criteria. Note that this involves modifying the ``standard''
+behaviour of the \texttt{CartGrid3D} thorn (to place the $z$-axis
+along one edge of the grid). This is accomplished by internally
+resetting the grid type to \texttt{byrange}, and then specifying
+ranges which are compatible with the cartoon conditions and with the
+appropriate number of grid points and ghost zones. Note that this
+involves a reset of otherwise non-steerable parameters, and so must be
+scheduled at \texttt{CCTK\_RECOVER\_PARAMETERS} and before the grid is
+set up.
+
+\section{Interaction with other thorns}
+\label{sec:interaction}
+
+Some thorns will need to know that a cartoon grid is being used in
+order to function properly. In principle, they should use the
+\texttt{cartoon\_active} parameter to check whether a cartoon grid is
+in use.
+
+In practice, however, to avoid dependencies on \texttt{Cartoon2D}, it
+is often the case that the source code for such thorns make use of
+\texttt{\#ifdef} statements to check whether \texttt{Cartoon2D} has
+been compiled in. Then, to check whether a cartoon grid is active,
+other thorn-specific parameters need to be set.
+
+For instance, if the \texttt{ADM\_BSSN} thorn is being used for
+evolution, then the parameter
+
+\begin{verbatim}
+  adm_bssn::cartoon = "yes"
+\end{verbatim}
+
+must be set. Similarly, the \texttt{ADM} evolution system requires
+\texttt{adm::cartoon} to be set.
+
+The \texttt{AHFinder} thorn requires that the parameter
+
+\begin{verbatim}
+  ahfinder::ahf_cartoon = "yes"
+\end{verbatim}
+
+be set in order to use a cartoon grid.
+
+\emph{Note that many thorns will require cartoon-specific
+modifications in order to be used with the \texttt{Cartoon2D}
+thorn. It should not be assumed that a given thorn will work with
+\texttt{Cartoon2D} unless it is specifically mentioned in the
+documentation or source code.}
+
+\section{Source code}
+
+The interface to the \texttt{Cartoon2D} thorn is through the routines
+contained in the \texttt{Cartoon2DBC.c} source file. These routines
+can be used by other thorns (eg. evolution thorns) to apply cartoon
+boundary conditions to grid functions whenever it is appropriate to do
+so. The three interface functions are:
+
+\begin{description}
+
+  \item[\texttt{BndCartoon2DGN(cGH *GH, int tensortype, const char*
+      group)}]
+    This function applies the cartoon boundary condition to the grid
+    functions in the group specified by the \emph{group} parameter.
+    The parameter \emph{tensortype} parameter should be one of
+    \begin{description}
+      \item[\texttt{TENSORTYPE\_SCALAR}] a scalar;
+      \item[\texttt{TENSORTYPE\_U}] a vector (single, upper index).
+      \item[\texttt{TENSORTYPE\_DDSYM}] a symmetric tensor with two
+	lower indices.
+    \end{description}
+
+  \item[\texttt{BndCartoon2DVN(cGH *GH, int tensortype, const char
+      *impvarname)}]
+    This function is like \texttt{BndCartoon2DGN()}, but operates on
+    individual grid functions rather than groups.
+
+  \item[\texttt{BndCartoon2DVI(cGH *GH, int tensortype, int vi)}]
+    This function is like \texttt{BndCartoon2DGN()}, but operates
+    takes a grid function index to indicate the grid function to which
+    the condition should be applied.
+
+\end{description}
+
+A corresponding Fortran wrapper for each of these functions is also
+included.
+
+Interpolation operators are defined in the file
+\texttt{interpolate.c}.
+
+The file \texttt{SetSym.c} contains routines which re-label the flat
+faces of the cartoon grid as \texttt{CARTOON\_NOSYM} boundaries. This
+prevents any other boundary condition (eg. physical or symmetry
+conditions) from being applied to these faces, as they are determined
+by the \texttt{Cartoon2D} thorn. These routines need to be scheduled
+before the first time boundary conditions are applied to any grid
+function.
+
+The file \texttt{SetGrid.c} contains the code to reset the grid
+dimensions in a cartoon-friendly way (see Section \ref{sec:regrid}) if
+the \texttt{byspacing} grid type is used. In this case, appropriate
+coordinate grid ranges are calculated so that the $(dx,dy,dz)$ values
+are preserved, and the parameters specifying the grid are reset. These
+are non-steerable, and so the routine must be run during the
+\texttt{CCTK\_RECOVER\_PARAMETERS} time bin in order to work. (This time
+bin is run even when checkpoint recovery is not being used.)
+
+%
+% FIXME: What's the published reference?
+%
+\begin{thebibliography}{9}
+  \bibitem{Alcubierre-etal-2001}
+    Miguel Alcubierre, Steven Brandt, Bernd Br\"ugmann, Daniel Holz,
+    Edward Seidel, Ryoji Takahashi, Jonathan Thornburg (2001)
+    \emph{Symmetry without symmetry: Numerical simulation of
+    Axisymmetric Systems using Cartesian Grids}, Int. J. Mod. Phys. D,
+    \textbf{10}, 273--289, (gr-qc/9908012).
+\end{thebibliography}
+
+\end{document}
\ No newline at end of file