From ca9950e3a72069b108dfb4c09ee29a01f7c8c249 Mon Sep 17 00:00:00 2001 From: jthorn Date: Sun, 21 May 2006 16:52:03 +0000 Subject: * put Boundary/ prefix on latex labels so they'll be unique across thorns when producing thorn guides for an entire arrangement * document the return value of Boundary_SelectVarforBC() Boundary_SelectVarforBCI() Boundary_SelectGroupforBC() Boundary_SelectGroupforBCI() * break an excessively-long paragraph right after the description of that return value git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/Boundary/trunk@286 6a38eb6e-646e-4a02-a296-d141613ad6c4 --- doc/documentation.tex | 73 +++++++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 32 deletions(-) diff --git a/doc/documentation.tex b/doc/documentation.tex index 6cd40aa..e3539d5 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -121,12 +121,12 @@ functions%\footnote{See appendix \ref{apx:fn_aliasing} for some notes register routines which provide a particular physical boundary condition, and also to select variables or groups of variables to have boundary conditions applied to whenever the \texttt{ApplyBCs} schedule -group is scheduled (see section \ref{schedule_groups}). In addition, +group is scheduled (see section \ref{Boundary/sec:schedule_groups}). In addition, an aliased function is provided which returns a list of grid variables -selected for a boundary condition (see appendix \ref{apx:symmetry}). +selected for a boundary condition (see appendix \ref{Boundary/apx:symmetry}). \subsection{Boundary condition registration} -\label{sec:bc_registration} +\label{Boundary/sec:bc_registration} To register a routine to provide some physical boundary condition, use \begin{verbatim} @@ -154,7 +154,7 @@ long argument name\= description\=\kill \texttt{num\_vars} \> number of entries passed in the following three arrays\\ \texttt{var\_indices} \> array of \texttt{num\_vars} variable indices selected for this boundary condition\\ \texttt{faces} \> array of \texttt{num\_vars} faces specifications -(see section \ref{faces})\\ +(see section \ref{Boundary/sec:faces})\\ \texttt{widths} \> array of \texttt{num\_vars} boundary widths (see below)\\ \texttt{table\_handles} \> array of \texttt{num\_vars} table handles%, which hold extra arguments for each application of the boundary condition to a grid variable \end{tabbing} @@ -169,7 +169,7 @@ clear how face information should be considered in the sorting, so it is not.) A null pointer can be passed for \texttt{function\_pointer}, in which case no routine is executed when \texttt{Boundary\_ApplyPhysicalBCs} is called (see section -\ref{schedule_groups}). +\ref{Boundary/sec:schedule_groups}). \subsection{Boundary condition selection} @@ -218,14 +218,22 @@ long argument name\= description\=\kill \texttt{group\_index} \> index of group of grid variables \end{tabbing} -The first two select a single grid variable for a boundary condition, -using either the variable name or index respectively. The second two -select an entire variable group, using either its name or index. Each -takes a faces specification, a boundary width, and a table handle as additional arguments. +Each of these functions returns 0 for success, or a negative error +code if something went wrong. + +\verb|Boundary_SelectVarForBC()| and \verb|Boundary_SelectVarForBCI()| +select a single grid variable for a boundary condition, +using either the variable name or index respectively. +\verb|Boundary_SelectGroupForBC()| and \verb|Boundary_SelectGroupForBCI()| +select an entire variable group, using either its name or index. + +Each of these functions takes a faces specification, a boundary width, +and a table handle as additional arguments. The faces specification is a single integer which identifies a set of faces to which to apply the boundary condition. See section -\ref{faces} for details. The boundary width is the thickness, in grid -points, of the boundaries. +\ref{Boundary/sec:faces} for details. The boundary width is the thickness, +in grid points, of the boundaries. + The table handle identifies a table which holds extra arguments for the particular boundary condition that is requested. @@ -235,28 +243,29 @@ array, which holds the width of each face of the boundary (for a $d$ dimensional grid variable). (The first element of the array holds the width of the `-x' face, the second the `+x' face, the third the `-y' face, etc.) -In some cases the table handle is required, so the -boundary condition, when it is called within the -\texttt{BoundaryConditions} schedule group (see section -\ref{schedule_groups}), will return an error code. However, in most -cases it is optional. If one uses an invalid table handle here (such -as -1), commonly used default values will be assumed for all arguments -(besides the explicit faces specification and boundary widths). Note that you, the user, -will be creating the table, so you may choose whatever options (such -as case sensitivity) you like. The case of the keys for which the -boundary conditions implemented in this thorn search are as given in the -documentation, which is currently all capitals. To be safe you may -choose to create case-insensitive tables, however cases sensitive -tables are slightly faster. + +In some cases the table handle is required, so the boundary condition, +when it is called within the \texttt{BoundaryConditions} schedule +group (see section \ref{Boundary/sec:schedule_groups}), will return +an error code. However, in most cases it is optional. If one uses +an invalid table handle here (such as -1), commonly used default +values will be assumed for all arguments (besides the explicit faces +specification and boundary widths). Note that you, the user, will +be creating the table, so you may choose whatever options (such as +case sensitivity) you like. The case of the keys for which the +boundary conditions implemented in this thorn search are as given +in the documentation, which is currently all capitals. To be safe +you may choose to create case-insensitive tables, however cases +sensitive tables are slightly faster. The name of the boundary condition must match that with which the boundary condition providing function was registered. These names are -case insensitive. See section \ref{sec:provided_bcs} for a list of +case insensitive. See section \ref{Boundary/sec:provided_bcs} for a list of boundary conditions provided by thorn \texttt{Boundary}. \subsection{Schedule groups} -\label{schedule_groups} +\label{Boundary/sec:schedule_groups} Implementation \texttt{Boundary} creates two schedule groups \begin{verbatim} @@ -281,7 +290,7 @@ gets executed exactly once for each selected grid variable. \subsection{Faces} -\label{faces} +\label{Boundary/sec:faces} The computational domain is assumed to be in the shape of a $n$-dimensional `rectangle', which has $2n$ $n-1$ dimensional faces. (Usually $n$ @@ -304,7 +313,7 @@ its argument), and $e_j$ represents the `$j$-direction' on the grid. \section{Provided boundary conditions} -\label{sec:provided_bcs} +\label{Boundary/sec:provided_bcs} Thorn \texttt{Boundary} also provides seven standard boundary conditions, which can be applied to one, two, or three dimensional grid variables. The boundary conditions available are @@ -615,7 +624,7 @@ direction. The radiative boundary condition that is implemented is \begin{equation} -\label{eqrad} +\label{Boundary/eq:eqrad} f = f_0 + \frac{u(r-vt)}{r}+\frac{h(r+vt)}{r} \end{equation} That is, outgoing radial waves with a $1/r$ @@ -623,7 +632,7 @@ fall off, and the correct asymptotic value $f_0$ are assumed, including the possibility of incoming waves (these incoming waves should be modeled somehow). -Condition~\ref{eqrad} above leads to the differential equation: +Condition~\ref{Boundary/eq:eqrad} above leads to the differential equation: \begin{equation} \frac{x^i}{r}\frac{\partial f}{\partial t} + v \frac{\partial f}{\partial x^i} @@ -1107,7 +1116,7 @@ There is no old interface to this boundary condition. \section{Appendix: Symmetry and non-local boundary conditions} -\label{apx:symmetry} +\label{Boundary/apx:symmetry} An additional aliased function is provided to allow one to retrieve a list of grid variables which are selected for any particular boundary @@ -1144,7 +1153,7 @@ int Boundary_SelectedGVs(CCTK_POINTER cctkGH, \end{tabbing} This function places a list of up to \texttt{array\_size} grid variable indices, sorted as described in section -\ref{sec:bc_registration}, into the array \texttt{var\_indices}. The +\ref{Boundary/sec:bc_registration}, into the array \texttt{var\_indices}. The corresponding (up to \texttt{array\_size}) faces specifications, boundary widths, and table handles are placed into the arrays \texttt{faces}, \texttt{boundary\_widths}, and -- cgit v1.2.3