diff options
Diffstat (limited to 'doc/documentation.tex')
| -rw-r--r-- | doc/documentation.tex | 408 |
1 files changed, 408 insertions, 0 deletions
diff --git a/doc/documentation.tex b/doc/documentation.tex new file mode 100644 index 0000000..b69e31e --- /dev/null +++ b/doc/documentation.tex @@ -0,0 +1,408 @@ +% *======================================================================* +% Cactus Thorn template for ThornGuide documentation +% Author: Ian Kelley +% Date: Sun Jun 02, 2002 +% $Header$ +% Thorn documentation in the latex file doc/documentation.tex +% will be included in ThornGuides built with the Cactus make system. +% The scripts employed by the make system automatically include +% pages about variables, parameters and scheduling parsed from the +% relevent thorn CCL files. +% +% This template contains guidelines which help to assure that your +% documentation will be correctly added to ThornGuides. More +% information is available in the Cactus UsersGuide. +% +% Guidelines: +% - Do not change anything before the line +% % BEGIN CACTUS THORNGUIDE", +% except for filling in the title, author, date etc. fields. +% - Each of these fields should only be on ONE line. +% - Author names should be sparated with a \\ or a comma +% - You can define your own macros are OK, but they must appear after +% the BEGIN CACTUS THORNGUIDE line, and must not redefine standard +% latex commands. +% - To avoid name clashes with other thorns, 'labels', 'citations', +% 'references', and 'image' names should conform to the following +% convention: +% ARRANGEMENT_THORN_LABEL +% For example, an image wave.eps in the arrangement CactusWave and +% thorn WaveToyC should be renamed to CactusWave_WaveToyC_wave.eps +% - Graphics should only be included using the graphix package. +% More specifically, with the "includegraphics" command. Do +% not specify any graphic file extensions in your .tex file. This +% will allow us (later) to create a PDF version of the ThornGuide +% via pdflatex. | +% - References should be included with the latex "bibitem" command. +% - use \begin{abstract}...\end{abstract} instead of \abstract{...} +% - For the benefit of our Perl scripts, and for future extensions, +% please use simple latex. +% +% *======================================================================* +% +% Example of including a graphic image: +% \begin{figure}[ht] +% \begin{center} +% \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure} +% \end{center} +% \caption{Illustration of this and that} +% \label{MyArrangement_MyThorn_MyLabel} +% \end{figure} +% +% Example of using a label: +% \label{MyArrangement_MyThorn_MyLabel} +% +% Example of a citation: +% \cite{MyArrangement_MyThorn_Author99} +% +% Example of including a reference +% \bibitem{MyArrangement_MyThorn_Author99} +% {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999), +% 1--16. {\tt http://www.nowhere.com/}} +% +% *======================================================================* + +% If you are using CVS use this line to give version information +% $Header$ + +\documentclass{article} + +% Use the Cactus ThornGuide style file +% (Automatically used from Cactus distribution, if you have a +% thorn without the Cactus Flesh download this from the Cactus +% homepage at www.cactuscode.org) +\usepackage{../../../../doc/latex/cactus} + +\begin{document} + +% The author of the documentation +\author{Cactus Maintainers $<$\code{cactusmaint@cactuscode.org}$>$} + +% The title of the document (not necessarily the name of the Thorn) +\title{Coordinate Base Thorn} + +% the date your document was last changed: +\date{$ $Date$ $} + +\maketitle + +% Do not delete next line +% START CACTUS THORNGUIDE + +% Add all definitions used in this documentation here: +\def\WHAGH{CCTK\_WHAGH} +\def\beforetable{\\[1mm]} + +\hyphenation{Coord} + +% Add an abstract for this thorn's documentation +\begin{abstract} +CoordBase provides a mechanism for registering coordinate systems, and +maintaining a database of coordinate systems and their coordinates, +using key-value tables. +\end{abstract} + + +\section{Introduction} + +Many applications which use Cactus will want to make use of coordinate +systems. The CoordBase thorn provides a method of registering +coordinate systems and their properties. Thorns which implement +coordinate systems will register the systems they provide with +CoordBase. Since coordinate systems are composed of a collection of +coordinates, the coordinates which comprise the systems are registered +with CoordBase as well. The data describing coordinate systems are +held on Cactus key-value tables. A schema for the format of these +tables is provided in section +\ref{CactusBase_CoordBase_coordinate_schema}. Developers are free to +compose and use their own schema, but are encouraged to use the one +detailed here, as this will be the standard for all of the core Cactus +thorns. + +CoordBase specifies an extensible set of coordinate properties. The +use of key-value tables to hold the these properties makes CoordBase +flexible and configurable. The coordinate values themselves can be +specified in a number of ways, depending on the nature of the +coordinate system. This way symmetries of the coordinates on the +computational grid can be exploited to minimize memory consumption. +Via a function call, one can easily acertain what coordinate system is +associated with any given grid variable, which is convenient for e.g.\ +I/O. A method of registering default coordinates for all grid +variables of a certain dimension makes it simple to specify which +coordinate systems should be associated with which grid variables. + +The coordinate infrastructure provided by CoordBase will work +seamlessly with AMR and multi-model codes. + +%extensible database of coordinate systems, coordinates, and their +%properties + +Thorns which provide coordinates will inherit from CoordBase, and +register both the coordinate systems they provide, and the default +coordinate systems for the appropriate dimension of grid variables. +In addition, one can associate a coordinate with any Cactus grid +variable, within a thorn's interface.ccl. +Coordinate systems specified in the interface.ccl override defaults +for the dimension. + +The coordinate functions in the Cactus flesh are deprecated with the +introduction of this thorn. Please use the functions provided here in +preference to those in the flesh. + + +\section{Coordinate system symmetries} + +Since computations performed with Cactus are done on a discrete +lattice, only a discrete set of coordinate values are used for any +coordinate system. The symmetries of how the coordinate values vary +on the grid points make coordinates fall into three types: +\emph{uniform}, \emph{nonuniform}, and \emph{warped}. (At least these +are the three cases that the CoordBase schema considers.) A uniform +coordinate varies from each of its neighbors by a constant. i.e.\ its +value can be determined from the index of the grid point from simply +an origin and constant `delta'. A nonuniform coordinate has a +spatially varying `delta'. For both uniform and nonuniform +coordinates, the coordinate values do not vary along the other +directions of the grid. (e.g.\ the $x$ coordinate will be the same +regardless of the `j' index of the grid point.) Thus one could +completely determine the coordinate values of a 3D system of +nonuniform coordinates by providing three 1D arrays. This later +assumption is relaxed for a warped coordinate; a warped coordinate +will vary across the entire grid. Recall that `coordinate lines' +(lines of constant coordinate value) cannot cross (because one n-tuple +of coordinate values would specify muliple points in space), so this +places a `bound' of sorts on the possible `warping' of the +coordinates. + +The type of a coordinate system will be the same as that of its +coordinates. If there are different types of coordinates within the +same system, then the coordinate system is \emph{mixed}. Note that a +warped coordinate system is the most general possible, so any +coordinate system could be regarded as warped if one wishes. + +\subsection{Specifying coordinate values} + +As mentioned above, for a uniform coordinate system, it is sufficient +to specify the origin and spacing for a uniform coordinate. One may +also specify a grid variable to hold the coordinate values, if +desired. See section \ref{CactusBase_CoordBase_coordinate_schema}. A +nonuniform coordinate can be specified with a 1D grid variable, if +desired, or an nD variable. A warped coordinate system will always +need a nD grid variable. FMR and AMR will need an nD grid +variable to specify the coordinate values. A mixed coordinate system +can use some combination of the above, or simply an nD grid variable. + + +\section{Coordinate Thorns} + +Generally coordinate thorns will allow the declaration of default +coordinate systems for a dimension to be controled by parameters. + +If a thorn attempts to register a default for a dimension which +already has a default registered, a level 1 warning will result, and +the default will be overwritten with the new default. Since the order +of execution of the registration calls will in general not be +specified, one must be careful when activating more than one coordinate thorn. + +Coordinate systems and defaults can be changed at any time throughout +a run, as can coordinate properties. +In general these are set at \WHAGH\ and CCTK\_BASEGRID, respectively. + +The coordinate thorns are responsible for filling out the portions of +the coordinate and coordinate system tables that are not written by +the registration routines. See sections +\ref{CactusBase_CoordBase_system_tables} and +\ref{CactusBase_CoordBase_coord_tables}. + +\section{Application thorns} + +Application thorns should check at CCTK\_PARAMCHECK to see if the correct +coordinate system is being used for each relevant grid variable. +While the old flesh API is still being used you may want to make this +merely a warning. +Use Coord\_GroupSystem() to find the coordinate system for groups (see +section \ref{CactusBase_CoordBase_APIs}). + + +\section{Coordinate APIs} +\label{CactusBase_CoordBase_APIs} + +\begin{verbatim} +int systemhandle = Coord_SystemRegister(const cGH *GH, + int dim, + const char *systemname) +\end{verbatim} +registers a coordinate system, along with its +dimension, with the CoordBase thorn. This will create a coordinate +system table, and return the handle of the table for success, or a +negative error code upon error. The possible errors are:\beforetable +\begin{tabular}{ll} +COORDERROR\_INVALIDDIM & invalid dimension passed in\\ +COORDERROR\_INVALIDNAME & invalid name passed in\\ +COORDERROR\_TABLEERROR & error from key-value or hash tables in flesh\\ +COORDERROR\_SYSTEMEXISTS & coordinate system of this name already exists\\ +\end{tabular} +\\These error codes are defined in CoordBase.h. CoordBase holds the +table handles on a GH extension, under the name ``CoordBase''. + +\begin{verbatim} +int systemhandle = Coord_SystemHandle(const cGH *GH, + const char *systemname) +\end{verbatim} +returns the handle for a given coordinate system, or +negative on error:\beforetable +\begin{tabular}{ll} + COORDERROR\_TABLEERROR & error from hash table\\ + COORDERROR\_NOSYSTEM & no coordinate system of this name is registered\\ +\end{tabular} + +\begin{verbatim} +int coordhandle = Coord_CoordRegister(const cGH *GH, + int systemhandle, + int direction, + const char *coordname) +\end{verbatim} +registers a coordinate within a coordinate system, in the specified +`direction'. (Direction in this context means the index in the +coordinate basis, which ranges from 1 to the dimension of the system.) +Coord\_CoordRegister() returns the coordinate handle, or negative for an +error:\beforetable +\begin{tabular}{ll} +COORDERROR\_INVALIDDIM & invalid `direction'\\ +COORDERROR\_INVALIDHANDLE & invalid handle passed in / coordinate system + does not exist\\ +COORDERROR\_TABLEERROR & error from hash or key-value tables in flesh\\ +COORDERROR\_COORDINATEEXISTS & coordinate already exists for this `direction'\\ +COORDERROR\_DUPLICATENAME & coordinate of this name already exists in this + system\\ +\end{tabular} + +\begin{verbatim} +int coordhandle = Coord_CoordHandle(const cGH *GH, + const char *coordname, + const char *systemname) +\end{verbatim} +returns the coordinate handle for a given coordinatate in a coordinate system, +or negative on error:\beforetable +\begin{tabular}{ll} +COORDERROR\_NOSYSTEM & no coordinate system of this name is registered\\ +COORDERROR\_TABLEERROR & error from hash table\\ +COORDERROR\_NOSUCHCOORD & no coordinate of the name is registered for this + system\\ +\end{tabular} + +\begin{verbatim} +int systemhandle = Coord_GroupSystem(const cGH *GH, + const char *groupname) +\end{verbatim} +returns the handle for the coordinate system associated with a group of grid +variables, or negative on error. +This can either be the default for coordinate systems of this +dimension, or the coordinate system that is specified in the +interface.ccl. Coordinate systems specified in interface.ccl will +override any defaults. The possible error codes are:\beforetable +\begin{tabular}{ll} +COORDERROR\_INVALIDGROUPNAME & no such group exists\\ +COORDERROR\_NOCOORDSYS & no coordinate system is associated with the + group +\end{tabular} + +\begin{verbatim} +int systemhandle = Coord_SetDefaultSystem(const cGH *GH, + const char *systemname) +\end{verbatim} +sets this coordinate system to be the default for grid variables of +the same dimension. It returns the handle of the system, or negative +for errors:\beforetable +\begin{tabular}{ll} +COORDERROR\_INVALIDNAME & no coordinate system of this name has been + registered\\ +COORDERROR\_NODIMENSION & coordinate system does not have a valid dimension\\ +COORDERROR\_DEFAULTEXISTS & grid variables of this dimension already have a \\ + & default coordinate system registered\\ +\end{tabular} +\\There can be a default coordinate system for each grid dimension. The +default system will apply for each grid variable of that dimension, +unless it is overridden. + + +\section{Coordinate Schema} +\label{CactusBase_CoordBase_coordinate_schema} + +\subsection{Coordinate System Tables} +\label{CactusBase_CoordBase_system_tables} + +Associated with each coordinate system is a table, which should have the +following entries:\beforetable +\begin{tabular}{|l|l|l|} +\hline +\textbf{key} & \textbf{data type} & \textbf{value}\\ +\hline +NAME & CCTK\_STRING & \code{Cart3d|Spher3d|....}\\ +DIMENSION & CCTK\_INT & \code{1,2,3,...}\\ +TYPE & CCTK\_STRING & \code{uniform|nonuniform|warped|mixed}\\ +COORDINATES & CCTK\_INT array & \verb|<coord1>,...<coord_dimension>|\\ +\hline +\end{tabular} +\\The values for the coordinates array are the handles for the +coordinate tables (see section +\ref{CactusBase_CoordBase_coord_tables}). The NAME and DIMENSION +fields are filled out when Coord\_SystemRegister() is called. The +COORDINATES field is filled out by Coord\_CoordRegister(). It is left +for the coordinate thorn to fill out the TYPE field. + +\subsection{Coordinate Tables} +\label{CactusBase_CoordBase_coord_tables} + +Associated with each coordinate of each coordinate system is another +table, which should have the following entries:\beforetable +\begin{tabular}{|l|l|l|} +\hline +\textbf{key} & \textbf{data type} & \textbf{values}\\ +\hline +SYSTEM & CCTK\_INT & \verb|<handle>|\\ +NAME & CCTK\_STRING & \code{x}\\ +DIRECTION & CCTK\_INT & \code{2}\\ +PHYSICALMIN & CCTK\_REAL & \code{0.0}\\ +COMPMIN & CCTK\_REAL & \\ +PHYSICALMAX & CCTK\_REAL & \\ +COMPMAX & CCTK\_REAL & \\ +TYPE & CCTK\_STRING & \verb/uniform|non-uniform|warped/\\ +TIMEDEPENDENT & CCTK\_INT & \verb/<yes (1)|no (0)>/\\ +DATATYPE & CCTK\_STRING & \\ +GAINDEX & CCTK\_INT & \\ +\hline +DELTA\footnotemark %{only for type=uniform} + & CCTK\_REAL & \code{147.372e16}\\ +\hline +\end{tabular} +\footnotetext{only for type=\code{uniform}} +\\ +Coord\_CoordRegister() fills out the SYSTEM, NAME, and DIRECTION +fields, and the COORDINATES field of the system table. The remaining +fields are the responsivility of the coordinate thorn. + +% Each of these fields should be explained... +% Though most are pretty self-explanatory. + + +\section{Specifying coordinate systems in the interface.ccl} + +Coordinate systems associated with grid variable groups can be +specified in the group's tags table, using the key \code{COORDSYSTEM}. +Below is a grid array which could represent a vector field on a +2-sphere. +\begin{verbatim} +CCTK_REAL SphericalVectorField TYPE=ARRAY DIM=2 TAGS='COORDSYSTEM="sphere2d" TENSORTYPE="vector"' +{ + field_theta, field_phi +} +\end{verbatim} +Even though another thorn has set a default for all 2D grid variables +to something else, Coord\_GroupSystem() will always return the handle +for sphere2d when called on this group. + +% Do not delete next line +% END CACTUS THORNGUIDE + +\end{document} |