Documentation of new boundary API.

Added footnote discussing handling of a 'noise bc'.

Removed appendix on function aliasing, as this is now discussed in
the Users' Guide.

Expanded on what faces spec might look like.


git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/Boundary/trunk@222 6a38eb6e-646e-4a02-a296-d141613ad6c4

1 files changed, 87 insertions, 60 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index cc34f5a..18d41ea 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -90,7 +90,18 @@ added if necessary.  Usually physical boundary conditions are local.
 A non-local physical boundary condition may arise e.g.~from a need to
 solve an elliptic equation at the boundary.  As opposed to symmetry
 boundary conditions, it only makes sense to have a single physical
-boundary condition active at a given grid point.
+boundary condition active at a given grid point.\footnote{It is
+possible that one may wish to modify the value of the field at the
+boundary, after a physical boundary condition has already been
+applied.  For example, one may wish to add a small amount of noise at
+the boundary to test code
+stability.  This added `term' is not a physical boundary condition in
+itself, however, and this cannot be registered as such.  To implement
+such a scheme one would treat the noise in a manner similar to
+symmetry boundary conditions, scheduling a routine during
+\texttt{BoundaryConditions} (see below), after \texttt{Boundary\_ApplyPhysicalBCs},
+which gets the list of selected variables and adds noise to their
+boundaries as desired.}
 
 To summarize, a `physics' thorn, such as a spacetime evolution thorn,
 knows only about physical boundary conditions.  Symmetry boundary
@@ -100,8 +111,9 @@ conditions are aspects of the grid and are managed by other thorns.
 \section{The generic boundary interface}
 
 The implementation \texttt{Boundary} provides a number of aliased
-functions\footnote{See appendix \ref{apx:fn_aliasing} for some notes
-on using aliased functions.}, which allow application thorns to
+functions%\footnote{See appendix \ref{apx:fn_aliasing} for some notes
+%on using aliased functions.}
+, which allow application thorns to
 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
@@ -129,7 +141,7 @@ boundary condition\\
 The function pointer takes arguments
 \begin{verbatim}
 (CCTK_POINTER cctkGH, CCTK_INT num_vars, CCTK_INT *var_indices, 
- CCTK_INT *faces, CCTK_INT *table_handles)
+ CCTK_INT *faces, CCTK_INT *widths, CCTK_INT *table_handles)
 \end{verbatim}
 (this defines the type \texttt{phys\_bc\_fn\_ptr}, above) where
 \begin{tabbing}
@@ -137,11 +149,13 @@ long argument name\= description\=\kill
 \texttt{cctkGH} \> pointer to the grid hierarchy\\
 \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})\\
+\texttt{faces} \> array of \texttt{num\_vars} faces specifications
+(see section \ref{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}
 The table handles hold extra arguments for each application of the boundary condition.
-The three arrays are sorted first on table handle, and then on
+The four arrays are sorted first on table handle, and then on
 variable index.  This way variables which have precisely the same
 boundary condition are grouped together, and within this grouping
 variables are sorted by index, so that variable groups are stored
@@ -160,24 +174,28 @@ use one of the following aliased functions:
 \begin{verbatim}
 Boundary_SelectVarForBC(CCTK_POINTER cctkGH,
                         CCTK_INT faces,
+                        CCTK_INT boundary_width,
                         CCTK_INT table_handle, 
                         CCTK_STRING var_name, 
                         CCTK_STRING bc_name)
 
 Boundary_SelectVarForBCI(CCTK_POINTER cctkGH,
                         CCTK_INT faces,
+                        CCTK_INT boundary_width,
                         CCTK_INT table_handle, 
                         CCTK_INT var_index, 
                         CCTK_STRING bc_name)
 
 Boundary_SelectGroupForBC(CCTK_POINTER cctkGH,
                           CCTK_INT faces,
+                          CCTK_INT boundary_width,
                           CCTK_INT table_handle, 
                           CCTK_STRING group_name, 
                           CCTK_STRING bc_name)
 
 Boundary_SelectGroupForBCI(CCTK_POINTER cctkGH,
                            CCTK_INT faces,
+                           CCTK_INT boundary_width,
                            CCTK_INT table_handle, 
                            CCTK_INT group_index, 
                            CCTK_STRING bc_name)
@@ -187,6 +205,7 @@ where
 long argument name\= description\=\kill
 \texttt{cctkGH} \> pointer to the grid hierarchy\\
 \texttt{faces} \> set of faces to which to apply the boundary condition\\
+\texttt{boundary\_width} \> width (in grid points) of the boundaries\\
 \texttt{table\_handle} \> handle for table which holds extra arguments for the boundary condition\\
 \texttt{var\_name} \> name of the grid variable\\
 \texttt{bc\_name} \> name of the boundary condition\\
@@ -198,18 +217,27 @@ long argument name\= description\=\kill
 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 and table handle as additional arguments.
+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 table handle identifies a table which
+\ref{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.  In some cases the table handle is required, so the
+requested.  
+For example, if a negative value is passed for the boundary width, then the
+boundary condition will look in this table for a $2d$-element integer
+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).  Note that you, the user,
+(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
@@ -258,7 +286,15 @@ subsets to bits will be provided in the include file
 \texttt{cctk\_Faces.h}.  For the moment there is only
 \texttt{CCTK\_ALL\_FACES}, which corresponds to the set of all faces
 of the domain.  If you need face specific calls immediately, please
-use the old interface for now.
+use the old interface for now.  
+
+The mapping of bits to faces will likely be the same as that used for
+the (optional) \texttt{BOUNDARY WIDTH} array.  Precisely, the rule is as
+follows.  For a $d$ dimensional grid variable, label the elements or
+bits by integers $i$ from $0$ to $2d-1$. Element or bit $i$ gets
+mapped to face $(-)^{i+1}e_{\lfloor i\rfloor}$, where ${}_{\lfloor
+\rfloor}$ designates the `floor' function (greatest integer less than
+its argument), and $e_j$ represents the `$j$-direction' on the grid.
 
 
 \section{Provided boundary conditions}
@@ -293,17 +329,23 @@ boundary conditions, which you would like to use instead.
 
 \subsection{General Comments}
 
-All the boundary conditions here optionally take a stencil
-size as an argument. The stencil size is used to determine how many
-points at the boundary should be updated with a boundary condition.
-For example, a stencil size of two in each direction means that the
-points at the boundary, as well as the points one in from the boundary
-will be set by the boundary condition. These boundary points are part
-of the total number of grid points that you have specified in the
-beginning of the run.  The stencil size is expressed by an array of
-$n$ integers for an $n$-dimensional grid variable.  In the future this
-will be increased to $2n$ integers, so that one can have a different
-stencil size on the `plus' and `minus' faces.
+%All the boundary conditions here optionally take a stencil
+%size as an argument. The stencil size is used to determine how many
+%points at the boundary should be updated with a boundary condition.
+%For example, a stencil size of two in each direction means that the
+%points at the boundary, as well as the points one in from the boundary
+%will be set by the boundary condition. These boundary points are part
+%of the total number of grid points that you have specified in the
+%beginning of the run.  The stencil size is expressed by an array of
+%$n$ integers for an $n$-dimensional grid variable.  In the future this
+%will be increased to $2n$ integers, so that one can have a different
+%stencil size on the `plus' and `minus' faces.
+Note that the number of boundary zones, as expressed in the
+\texttt{boundary\_width} argument or the \texttt{BOUNDARY WIDTH}
+array, is taken from the total number of grid points presented by
+Cactus through \texttt{cctk\_lssh}, etc.  
+%In this sense they do not
+%somehow `lie outside the grid', as `external ghostzones'.
 
 For the moment, these boundary routines may not work properly on
 grid arrays.  
@@ -380,7 +422,7 @@ following additional arguments:\\[1mm]
 \textbf{key} & \textbf{variable type} & \textbf{description} & \textbf{default value}\\
 \hline
 SCALAR & CCTK\_REAL & the scalar value & 0.0\\
-STENCIL WIDTH & CCTK\_INT array & stencil widths & 1 in all directions\\
+BOUNDARY WIDTH & CCTK\_INT array & stencil width for each face & n/a\\
 \hline
 \end{tabular}
 
@@ -480,7 +522,7 @@ following additional arguments:\\[1mm]
 \hline
 \textbf{key} & \textbf{variable type} & \textbf{description} & \textbf{default value}\\
 \hline
-STENCIL WIDTH & CCTK\_INT array & stencil widths & 1 in all directions\\
+BOUNDARY WIDTH & CCTK\_INT array & stencil width for each face & n/a\\
 \hline
 \end{tabular}
 
@@ -626,10 +668,10 @@ following additional arguments:\\[1mm]
 \textbf{key} & \textbf{variable type} & \textbf{description} & \textbf{default value}\\
 \hline
 LIMIT & CCTK\_REAL & $f_0$ & 0.0\\
-STENCIL WIDTH & CCTK\_INT array & stencil widths & 1 in all directions\\
 PREVIOUS TIME LEVEL & CCTK\_INT or CCTK\_STRING & GV which holds the & Cactus previous time level\\
 && previous time level&\\
 SPEED & CCTK\_REAL & wave speed $v$& 1.0\\
+BOUNDARY WIDTH & CCTK\_INT array & stencil width for each face & n/a\\
 \hline
 \end{tabular}
 \\[1mm] The default behavior is to use the Cactus previous time level,
@@ -771,11 +813,12 @@ required, so a valid table handle is required as well.  The keys read are
 \textbf{key} & \textbf{variable type} & \textbf{description} & \textbf{default value}\\
 \hline
 COPY FROM & CCTK\_INT or CCTK\_STRING & GV to copy from & \emph{no default}\\
-STENCIL WIDTH & CCTK\_INT array & stencil widths & 1 in all directions\\
+BOUNDARY WIDTH & CCTK\_INT array & stencil width for each face & n/a\\
 \hline
 \end{tabular}
 \\[1mm]
-The ``STENCIL WIDTH'' table entry is of course still optional.
+(The \texttt{BOUNDARY WIDTH} table entry is only necessary if
+the \texttt{boundary\_width} parameter is negative.)
 
 
 \subsection{Old interface}
@@ -887,8 +930,8 @@ following additional arguments:\\[1mm]
 \textbf{key} & \textbf{variable type} & \textbf{description} & \textbf{default value}\\
 \hline
 FINF & CCTK\_REAL & $f_0$ & 1.0\\
-STENCIL WIDTH & CCTK\_INT array & stencil widths & 1 in all directions\\
 DECAY POWER & CCTK\_INT & $n$ & 1\\
+BOUNDARY WIDTH & CCTK\_INT array & stencil width for each face & n/a\\
 \hline
 \end{tabular}
 
@@ -964,7 +1007,7 @@ following additional arguments:\\[1mm]
 \hline
 \textbf{key} & \textbf{variable type} & \textbf{description} & \textbf{default value}\\
 \hline
-STENCIL WIDTH & CCTK\_INT array & stencil widths & 1 in all directions\\
+BOUNDARY WIDTH & CCTK\_INT array & stencil width for each face & n/a\\
 \hline
 \end{tabular}
 
@@ -1078,33 +1121,37 @@ int Boundary_SelectedGVs(CCTK_POINTER cctkGH,
                          CCTK_INT array_size,
                          CCTK_POINTER var_indices,
                          CCTK_POINTER faces,
+                         CCTK_POINTER boundary_widths,
                          CCTK_POINTER table_handles,
                          CCTK_STRING bc_name)
 \end{verbatim}
 \begin{tabbing}
-\texttt{table\_handles} \= description \=\kill
+\texttt{table\_handlesss} \= description \=\kill
 \texttt{cctkGH} \> pointer to the grid hierarchy\\
 \texttt{array\_size} \> size of arrays pointed to by the next three arguments\\
 \texttt{var\_indices} \> array of integers into which the selected variables' grid variable indices will be placed\\
 \texttt{faces} \> array of integers into which the faces specification for each selected grid variable will be placed\\
+\texttt{boundary\_widths} \> array of integers which holds the \texttt{boundary\_width} parameter for each selected GV\\
 \texttt{table\_handles} \> array of integers into which the table handle for each selected grid variable will be placed\\
 \texttt{bc\_name} \> name of boundary condition
 \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
-corresponding (up to \texttt{array\_size}) faces specifications and
-table handles are placed into the arrays \texttt{faces} and
+corresponding (up to \texttt{array\_size}) faces specifications,
+boundary widths, and table handles are placed into the arrays
+\texttt{faces}, \texttt{boundary\_widths}, and
 \texttt{table\_handles}, respectively.  (If the list contains
 $n<$\texttt{array\_size} elements, then only $n$ elements are placed
-into the arrays \texttt{var\_indices}, \texttt{faces}, and
-\texttt{table\_handles}.)  To retrieve a list of all selected grid
-variables (for all boundary conditions), pass a null pointer for
-\texttt{bc\_name}.  The return value is the number elements of the
-requested list, so \texttt{Boundary\_SelectedGVs} can be called first
-with \texttt{var\_indices} equal to zero to determine how much memory
-to allocate for the arrays \texttt{var\_indices}, \texttt{faces}, and
-\texttt{table\_handles}.
+into the arrays \texttt{var\_indices}, \texttt{faces},
+\texttt{boundary\_widths}, and \texttt{table\_handles}.)  To retrieve
+a list of all selected grid variables (for all boundary conditions),
+pass a null pointer for \texttt{bc\_name}.  The return value is the
+number elements of the requested list, so
+\texttt{Boundary\_SelectedGVs} can be called first with
+\texttt{var\_indices} equal to zero to determine how much memory to
+allocate for the arrays \texttt{var\_indices}, \texttt{faces},
+\texttt{boundary\_widths}, and \texttt{table\_handles}.
 
 A non-local boundary condition must register a null pointer as its
 providing function in\\ \texttt{Boundary\_RegisterPhysicalBC}, so that
@@ -1112,26 +1159,6 @@ its name exists in the database of available boundary conditions, yet
 no extra routine is called when \texttt{Boundary\_ApplyPhysicalBCs} is
 executed.
 
-
-\section{Appendix: Using aliased functions}
-\label{apx:fn_aliasing}
-Since this is not yet documented anywhere else, here are some notes on
-how to use aliased functions.
-
-To use e.g.~\texttt{Boundary\_SelectGroupForBC} in your thorn, add the
-following code to your \texttt{interface.ccl}
-\begin{verbatim}
-CCTK_INT FUNCTION Boundary_SelectGroupForBC CCTK_POINTER GH, CCTK_INT faces, \
-  CCTK_INT table_handle, CCTK_STRING group_name, CCTK_STRING bc_name
-USES FUNCTION Boundary_SelectGroupForBC
-\end{verbatim}
-For C code, this allows you to call the function with the given
-arguments in your thorn.  For Fortran code, simply place an extra integer
-argument at the beginning which is the return value.
-%  At the moment, for Fortran thorns, please comment out the above lines in your \texttt{interface.ccl}.
-For the other aliased routines simply change the arguments appropriately.
-
-
 % Do not delete next line
 % END CACTUS THORNGUIDE