From 784ad3216fdca23fbd5bc0647bb2121d7dd4f5d9 Mon Sep 17 00:00:00 2001 From: jthorn Date: Wed, 24 Apr 2002 17:31:02 +0000 Subject: 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 --- doc/documentation.tex | 273 +++++++++++++++++++++++++++++++++++++++++++------- 1 file 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} -- cgit v1.2.3