Updates to the documentation.

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

3 files changed, 62 insertions, 76 deletions

diff --git a/doc/cartoon_plane.eps b/doc/cartoon_plane.eps
index a8d1c1b..3b0c671 100644
--- a/doc/cartoon_plane.eps
+++ b/doc/cartoon_plane.eps
@@ -1,7 +1,7 @@
 %!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
+%%CreationDate: Wed Apr 17 09:42:17 2002
 %%For: dp@nbdell15 (Denis Pollney,,,)
 %%BoundingBox: 0 0 239 491
 %%Magnification: 1.0000
@@ -92,10 +92,10 @@ $F2psBegin
 %
 % 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 
+n 2250 1125 m 4275 3150 l 4275 7650 l 2250 5625 l
+ cp gs col6 0.90 shd ef gr gs col0 s gr 
 % Polyline
-n 2700 1125 m 2925 1125 l 4950 3150 l 4725 3150 l 2700 1125 l
+n 2700 1125 m 2925 1125 l 4950 3150 l 4725 3150 l
  cp gs col0 s gr 
 % Polyline
 n 3825 3150 m 4050 3150 l 4050 7650 l 3825 7650 l
@@ -110,25 +110,19 @@ n 4500 3150 m 4725 3150 l 4725 7650 l 4500 7650 l
 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
+n 1800 1125 m 3825 3150 l 3825 7650 l 1800 5625 l
  cp gs col0 s gr 
 % Polyline
-n 1800 1125 m 2025 1125 l 4050 3150 l 3825 3150 l 1800 1125 l
+n 1800 1125 m 2025 1125 l 4050 3150 l 3825 3150 l
  cp gs col0 s gr 
 % Polyline
-n 2025 1125 m 2250 1125 l 4275 3150 l 4050 3150 l 2025 1125 l
+n 2025 1125 m 2250 1125 l 4275 3150 l 4050 3150 l
  cp gs col0 s gr 
 % Polyline
-n 2475 1125 m 2700 1125 l 4725 3150 l 4500 3150 l 2475 1125 l
+n 2475 1125 m 2700 1125 l 4725 3150 l 4500 3150 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
+n 2025 1125 m 4050 3150 l 4050 7650 l 2025 5625 l
  cp gs col0 s gr 
 % Polyline
 15.000 slw
@@ -158,6 +152,13 @@ n 4545 5625 m
 
 % arrowhead
 n 4993 5685 m 5233 5625 l 4993 5565 l 4993 5685 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+7.500 slw
+n 2250 1125 m 2475 1125 l 4500 3150 l 4275 3150 l
+ cp gs col6 0.70 shd ef gr gs col0 s gr 
+% Polyline
+n 4275 3150 m 4500 3150 l 4500 7650 l 4275 7650 l
+ cp gs col6 0.80 shd ef gr gs col0 s gr 
 /Times-Roman ff 270.00 scf sf
 5445 5715 m
 gs 1 -1 sc (y) col0 sh gr
diff --git a/doc/cartoon_plane.fig b/doc/cartoon_plane.fig
index 727019d..244e865 100644
--- a/doc/cartoon_plane.fig
+++ b/doc/cartoon_plane.fig
@@ -7,8 +7,8 @@ A4
 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 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 2700 1125 2925 1125 4950 3150 4725 3150 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
@@ -17,22 +17,16 @@ Single
 	 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 3 0 1 0 3 50 0 -1 0.000 0 0 -1 0 0 5
+	 1800 1125 3825 3150 3825 7650 1800 5625 1800 1125
+2 3 0 1 0 3 50 0 -1 0.000 0 0 -1 0 0 5
+	 1800 1125 2025 1125 4050 3150 3825 3150 1800 1125
+2 3 0 1 0 3 50 0 -1 0.000 0 0 -1 0 0 5
+	 2025 1125 2250 1125 4275 3150 4050 3150 2025 1125
+2 3 0 1 0 3 50 0 -1 0.000 0 0 -1 0 0 5
+	 2475 1125 2700 1125 4725 3150 4500 3150 2475 1125
+2 3 0 1 0 3 50 0 -1 0.000 0 0 -1 0 0 5
+	 2025 1125 4050 3150 4050 7650 2025 5625 2025 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
@@ -42,6 +36,12 @@ Single
 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
+2 3 0 1 0 6 60 0 18 0.000 0 0 -1 0 0 5
+	 2250 1125 4275 3150 4275 7650 2250 5625 2250 1125
+2 3 0 1 0 6 50 0 14 0.000 0 0 -1 0 0 5
+	 2250 1125 2475 1125 4500 3150 4275 3150 2250 1125
+2 2 0 1 0 6 50 0 16 0.000 0 0 -1 0 0 5
+	 4275 3150 4500 3150 4500 7650 4275 7650 4275 3150
 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
index 61fe9fd..686ed86 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -51,7 +51,7 @@ 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.
+to using the thorn as it is currently implemented.
 
 \section{Basic usage}
 
@@ -86,18 +86,17 @@ Only a small number of parameters need to be set to use
 
 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"
+activethorns                            = "cartoon2d cartgrid3d pugh"
 
-cartoon2d::cartoon_active		= "yes"
-cartoon2d::order                	= 3
-cartoon2d::allow_grid_resize		= "yes"
+cartoon2d::cartoon_active               = "yes"
+cartoon2d::order                        = 3
+cartoon2d::allow_grid_resize            = "yes"
 
 grid::type                              = "byspacing"
-grid::domain				= "bitant"
-grid::bitant_plane			= "xy"
+grid::domain                            = "bitant"
+grid::bitant_plane                      = "xy"
 grid::dxyz                              = 0.2
 
 driver::global_nx                       = 16
@@ -108,17 +107,15 @@ 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
+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"
+grid::avoid_originy                     = "no"
 
 \end{verbatim}
-
-The following features are of note:
-
+The following features are worth noting:
 \begin{itemize}
 
   \item The \texttt{order} parameter specifies that 3rd order
@@ -136,25 +133,22 @@ The following features are of note:
   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
+  \item Though not necessary, it is 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$.
+  \item The \texttt{avoid\_originy} parameter needs to be turned off
+    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.
+appropriately with \texttt{Cartoon2D}. For instance, see Section
+\ref{sec:interaction}. Examples of working parameter files can be
+found in the \texttt{Cartoon2D/test/} directory.
 
 \begin{figure}
   \centering
@@ -190,8 +184,8 @@ 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
+of grid points. However, using this method it can 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
@@ -220,24 +214,18 @@ 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
-
+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
-
+\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
@@ -260,10 +248,10 @@ so. The three interface functions are:
       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
+    The \emph{tensortype} argument 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\_U}] a vector (single, upper index);
       \item[\texttt{TENSORTYPE\_DDSYM}] a symmetric tensor with two
 	lower indices.
     \end{description}
@@ -303,9 +291,6 @@ 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,