diff options
Diffstat (limited to 'doc/documentation.tex')
| -rw-r--r-- | doc/documentation.tex | 318 |
1 files changed, 318 insertions, 0 deletions
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 |