From eb947858fba56cf963f0851e15a87a6dbfc71318 Mon Sep 17 00:00:00 2001 From: pollney Date: Wed, 17 Apr 2002 07:01:23 +0000 Subject: Added some documentation. git-svn-id: http://svn.cactuscode.org/arrangements/CactusNumerical/Cartoon2D/trunk@28 eec4d7dc-71c2-46d6-addf-10296150bf52 --- doc/cartoon_plane.eps | 171 +++++++++++++++++++++++++++ doc/cartoon_plane.fig | 47 ++++++++ doc/documentation.tex | 318 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 536 insertions(+) create mode 100644 doc/cartoon_plane.eps create mode 100644 doc/cartoon_plane.fig create mode 100644 doc/documentation.tex (limited to 'doc') 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 -- cgit v1.2.3