Major rewrite:

* Add lots of description of how to specify the grid type, size,
  also symmetries.  Also clarify ghost-zone and symmetry-zone semantics
  of driver::global_n[xyz] parameters.  Also a few latex tidyups.
* Also fix missing includes line and #include in example of registering
  symmetries


git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/CartGrid3D/trunk@150 c78560ca-4b45-4335-b268-5f3340f3cb52

1 files changed, 237 insertions, 36 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 8a79610..23224af 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -1,44 +1,235 @@
 \documentclass{article}
+
+\def\eg{\hbox{eg.}}
+\def\ie{\hbox{i.e.}}
+
 \begin{document}
 
 \title{CartGrid3D}
-\author{Gabrielle Allen, Gerd Lanfermann}
-\date{1999}
+\author{Gabrielle Allen, Gerd Lanfermann, Joan Masso;\\
+	this documentation by Jonathan Thornburg}
+\date{$ $Id$ $}
 \maketitle
 
-\abstract{Cartesian coordinates and symmetries for 3D grids}
+\abstract{
+{\tt CartGrid3D} allows you to set up coordinates on a 3D Cartesian
+grid in a flexible manner.  You can choose different grid domains
+(\eg{} octant) to allow you to exploit any symmetry in your problem.
+{\tt CartGrid3D} also provides routines for registering symmetries
+of grid functions and applying symmetry conditions across the
+coordinate axes.
+	 }
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Specifying the Grid Symmetry}
+
+You specify the grid symmetry (or lack thereof) with the
+\verb|grid::domain| parameter:
+\begin{description}
+\item[{\tt grid::domain = "full"}]\mbox{}\\
+	There are no symmetries.
+\item[{\tt grid::domain = "bitant"}]\mbox{}\\
+	The grid includes only the $z \ge 0$ half-space
+	(plus symmetry zones); there is a reflection symmetry
+	across the $z=0$ plane.
+\item[{\tt grid::domain = "quadrant"}]\mbox{}\\
+	The grid includes only the $\{x \ge 0, y \ge 0\}$ quadrant
+	(plus symmetry zones); there is a reflection symmetry
+	across both the $x=0$ plane and the $y=0$ plane.
+\item[{\tt grid::domain = "octant"}]\mbox{}\\
+	The grid includes only the $\{x \ge 0, y \ge 0, z \ge 0\}$
+	octant (plus symmetry zones); there is a reflection symmetry
+	across each of the $x=0$ plane, the $y=0$ plane, and the $z=0$
+	plane.
+\end{description}
+
+In each case except \verb|grid::domain = "full"|, symmetry zones are
+introduced just on the ``other side'' of each symmetry grid boundary.
+Each symmetry zone has a width (perpendicular to the boundary) of
+\verb|driver::ghost_size| extra grid points.  For centered 2nd~order
+finite differencing, a width of \verb|driver::ghost_size = 1| should be
+sufficient, but for (centered) 4th~order finite differencing, or for
+upwinded 2nd~order, a width of \verb|driver::ghost_size = 2| is needed.
+Making \verb|driver::ghost_size|
+too large is fairly harmless (it just slightly reduces performance),
+but making it too small will almost certainly result in horribly wrong
+finite differencing near the symmetry boundaries, and may also result
+in core dumps from out-of-range array accessing.
+
+Note that the symmetry zones must be explicitly included in
+\verb|driver::global_nx|, \verb|driver::global_ny|, and
+\verb|driver::global_nz|, but should {\em not\/} be included in any
+of the \verb|grid::type = "byrange"| parameters \verb|grid::xmin|,
+\verb|grid::xmax|, \verb|grid::ymin|, \verb|grid::ymax|, \verb|grid::zmin|,
+\verb|grid::zmax|, \verb|grid::xyzmin|, and/or \verb|grid::xyzmax|
+described in the next section.
+
+Note also that \verb|driver::global_nx|, \verb|driver::global_ny|,
+and \verb|driver::global_nz| do {\em not\/} include any ghost zones
+introduced for multiprocessor synchronization.  (For more information
+on ghost zones, see the section ``Ghost Size'' in the ``Cactus Variables''
+chapter of the Cactus Users' Guide.)
 
-\section{Purpose}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-Allows you to set up coordinates on a 3D Cartesian grid in a 
-flexible manner. Different grid domains (e.g. octant) can 
-be chosen to allow you to exploit any symmetry in your 
-problem. Routines for registering symmetries of grid functions
-and applying symmetry conditions across the coordinate axes 
-are provided.
+\section{Specifying the Grid Size, Range, and Spacing}
 
-\section{Comments}
+\verb|CartGrid3D| provides several different methods for setting
+up the integer {\em grid size\/} (\eg{} 128), floating-point
+{\em grid spacing\/} (\eg{} 0.1), and floating-point {\em grid range\/}
+(\eg{} 12.8).%%%
+\footnote{%%%
+	 If you're AMR-ing, this all refers to the
+	 coarsest or base grid.%%%
+	 }%%%
+{}  You specify which method to use, with the \verb|grid::type| parameter:
+\begin{description}
+\item[{\tt grid::type = "byrange"}]\mbox{}\\
+	You specify the $x$, $y$, and $z$ grid ranges, either with
+	separate \verb|grid::xmin|, \verb|grid::xmax|, \verb|grid::ymin|,
+	\verb|grid::ymax|, \verb|grid::zmin|, and \verb|grid::zmax|
+	parameters, or with the \verb|grid::xyzmin| and
+	\verb|grid::xyzmax| parameters.  The grid spacings are then
+	determined automagically from this information and the
+	\verb|driver::global\_nx|, \verb|driver::global\_ny|, and
+	\verb|driver::global\_nz| grid-size parameters.  You should
+	also chose the \verb|grid::domain| parameter consistent with
+	all these other parameters.  (It's not clear whether or not
+	the code ever explicitly checks this.)
+\item[{\tt grid::type = "box"}]\mbox{}\\
+	This is a special case of \verb|grid::type = "byrange"|
+	with the grid ranges hard-wired to
+	\verb|grid::xyzmin = -0.5| and \verb|grid::xyzmax = +0.5|.
+\item[{\tt grid::type = "byspacing"}]\mbox{}\\
+	You specify the $x$, $y$, and $z$ grid spacings, either with
+	separate \verb|grid::dx|, \verb|grid::dy|, and \verb|grid::dz|
+	parameters, or with the \verb|grid::dxyz| parameter.  You also
+	specify the grid symmetry with the \verb|grid::domain| parameter.
+	The $x$, $y$, and $z$ grid ranges are then determined automagically
+	from this information and the \verb|driver::global_nx|,
+	\verb|driver::global_ny|, and \verb|driver::global_nz|
+	grid-size parameters:  Each coordinate's range is chosen
+	to be either symmetric about zero, or to extend from 0 up
+	to a maximum value.
+\end{description}
 
-\subsection{Coordinates}
+There are also a number of optional parameters which can be used
+to specify whether or not it's ok to have a grid point with an $x$,
+$y$, and/or $z$ coordinate exactly equal to 0:
+\begin{description}
+\item[{\tt grid::no\_originx}]
+\item[{\tt grid::no\_originy}]
+\item[{\tt grid::no\_originz}]
+\item[{\tt grid::no\_origin}]\mbox{}\\
+	These parameters are all deprecated -- don't use them!
+\item[{\tt grid::avoid\_originx}]\mbox{}\\
+	This is a Boolean parameter; if set to true
+	(\verb|grid::avoid_originx = "true"| or
+	\verb|grid::avoid_originx = "yes"| or
+	\verb|grid::avoid_originx = 1|) then the grid will be
+	``half-centered'' across $x=0$, \ie{} there will be
+	grid points at
+	\dots,
+	$x = - \frac{3}{2} \Delta x$,
+	$x = - \frac{1}{2} \Delta x$,
+	$x = + \frac{1}{2} \Delta x$,
+	$x = + \frac{3}{2} \Delta x$,
+	\dots,
+	but not at $x=0$.
+\item[{\tt grid::avoid\_originy}]\mbox{}\\
+	Same thing for $y$.
+\item[{\tt grid::avoid\_originz}]\mbox{}\\
+	Same thing for $z$.
+\item[{\tt grid::avoid\_origin}]\mbox{}\\
+	Same thing for all 3 axes $x$ and $y$ and $z$, \ie{}
+	no grid point will have $x=0$ or $y=0$ or $z=0$.
+\end{description}
 
-The Cartesian coordinates supplied by this thorn are
-grid functions with the standard names {\tt x}, {\tt y}, and
-{\tt z}. To use these coordinates you need to {\tt inherit}
-from {\tt grid}.  The coordinates are
-registered with the flesh using the same names "x", "y" 
-and "z". In addition a grid function {\tt r} (registered as
-"r") is provided, containing the radial coordinate from
-the origin where
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{An Example}
+
+Here is an example of setting up a grid using the {\tt PUGH} unigrid
+driver.  The relevant parts of the parameter file are as follows:
+\begin{verbatim}
+# PUGH
+driver::ghost_size = 2
+driver::global_nx = 61
+driver::global_ny = 61
+driver::global_nz = 33
+
+# CartGrid3D
+grid::avoid_origin = "no"
+grid::domain = "bitant"
+grid::type = "byrange"
+grid::xmin = -3.0
+grid::xmax = +3.0
+grid::ymin = -3.0
+grid::ymax = +3.0
+grid::zmin =  0.0
+grid::zmax = +3.0
+\end{verbatim}
+
+The resulting Cactus output (describing the grid) is as follows:
+\begin{verbatim}
+INFO (CartGrid3D): Grid Spacings:
+INFO (CartGrid3D):  dx=>1.0000000e-01  dy=>1.0000000e-01  dz=>1.0000000e-01  
+INFO (CartGrid3D): Computational Coordinates:
+INFO (CartGrid3D):  x=>[-3.000, 3.000]  y=>[-3.000, 3.000]  z=>[-0.200, 3.000]  
+INFO (CartGrid3D): Indices of Physical Coordinates:
+INFO (CartGrid3D):  x=>[0,60]  y=>[0,60]  z=>[2,32]  
+INFO (PUGH): Single processor evolution
+INFO (PUGH): 3-dimensional grid functions
+INFO (PUGH):   Size: 61 61 33
+\end{verbatim}
+
+Since there's no symmetry in the $x$ and $y$ directions, the grid
+is set up just as specified, with floating-point coordinates running
+from $-3.0$ to $3.0$ inclusive, and 61~grid points with integer grid
+indices $[0,60]$ (C) or $[1,61]$ (Fortran).
+
+However, in the $z$ direction there's a reflection symmetry across the
+$z=0$ plane, so the specified range of the grid, $z \in [0.0,3.0]$,
+is automagically widened to include the symmetry zone of
+\verb|driver::ghost_size = 2| grid points.  The grid thus actually
+includes the range of floating-point coordinates $z \in [-0.2,3.0]$.
+The original specification of 33~grid points is left alone, however,
+so the grid points have integer array indices $[0,32]$ (C) or
+$[1,33]$ (Fortran).
+The ``physical'' (\ie{} non-symmetry-zone) part of the grid is
+precisely the originally-specified range, $z \in [0.0,3.0]$, and
+has the integer array indices $[2,32]$ (C) or $[3,33]$ (Fortran).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Coordinates}
+
+\verb|CartGrid3D| defines (registers) two coordinate systems:
+\verb|cart3d| and \verb|spher3d|.
+
+The Cartesian coordinates supplied by this thorn are grid functions
+with the standard names \verb|x|, \verb|y|, and \verb|z|.  To use
+these coordinates you need to inherit from \verb|grid|, \ie{} you
+need to have an
+\begin{verbatim}
+inherits: grid
+\end{verbatim}
+line in your \verb|interface.ccl| file.
+In addition a grid function \verb|r| is provided, containing the
+radial coordinate from the origin where
 $$
 r = \sqrt{x^2+y^2+z^2}
 $$
 
-{\tt CartGrid3D} registers the lower and upper range of each coordinate
+\verb|CartGrid3D| registers the lower and upper range of each coordinate
 with the flesh.
 
-\subsection{Symmetries}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-If your problem and initial data allow it, {\tt CartGrid3D}
+\section{Symmetries for Grid Functions}
+
+If your problem and initial data allow it, \verb|CartGrid3D|
 allows you to enforce either an even or odd parity
 symmetry condition for any grid functions at each
 coordinate axes. For a function $\phi(x,y,z)$,
@@ -51,26 +242,33 @@ $$
 \phi(-x,y,z) = -\phi(x,y,z)
 $$
 
-Note that the symmetries will only be enforced if a 
-symmetry domain is chosen (that is, if 
-{\tt domain} is {\tt octant}, {\tt quadrant} or {\tt bitant}).
+Note that the symmetries will only be enforced if a symmetry domain
+is chosen (that is, if \verb|grid::domain| is set to something other than
+\verb|grid::domain = "full"|.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \subsection{Registering Symmetry Behaviour}
 
 Each grid function can register how it behaves under a coordinate
 change using function calls in {\tt CartGrid3D}. These symmetry
-properties can then be used by other thorns, for example {\tt
-CactusBase/Boundary} uses them to enforce symmetry boundary conditions
-across coordinate axis. Symmetries should obviously be registered
-before they are used, but since they can be different for different grids, 
-they must be registered {\it after} the {\tt CCTK\_STARTUP} timebin. The
-usual place to register symmetries is in the {\tt CCTK\_BASEGRID} timebin.
+properties can then be used by other thorns, for example
+{\tt CactusBase/Boundary} uses them to enforce symmetry boundary
+conditions across coordinate axis. Symmetries should obviously be
+registered before they are used, but since they can be different
+for different grids, they must be registered {\it after} the
+{\tt CCTK\_STARTUP} timebin. The usual place to register symmetries
+is in the {\tt CCTK\_BASEGRID} timebin.
 
 For example, to register the symmetries of the {\it xy} component of the
-metric tensor from C
-
-{\tt
+metric tensor from C, you first need to get access to the include file
+by putting the line
 \begin{verbatim}
+uses include symmetry.h
+\end{verbatim}
+in your \verb|interface.ccl| file.  Then in your thorn you can write (C)
+\begin{verbatim}
+#include "symmetry.h"
 static int one=1;
 int sym[3];
 sym[0] = -one;
@@ -78,11 +276,14 @@ sym[1] = -one;
 sym[2] =  one;
 SetCartSymVN(cctkGH, sym,"einstein::gxy");
 \end{verbatim}
-}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 % Automatically created from the ccl files by using gmake thorndoc
 \include{interface}
 \include{param}
 \include{schedule}
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \end{document}