\begin{cactuspart}{\code{Driver\_*} Functions Reference}{}{$Revision$}
\label{part:DriverReference}
\renewcommand{\thepage}{\Alph{part}\arabic{page}}

In this chapter all \code{Driver\_*} Cactus functions are described.
These functions are callable from C or Fortran thorns.

In the functions below, \texttt{where} refers to an integer whose values are defined in \texttt{cctk\_Constants.h}. The basic values are \texttt{WH\_INTERIOR}, \texttt{WH\_BOUNDARY}, and \texttt{WH\_GHOSTS}. Other values are created by bitwise or: \texttt{WH\_EXTERIOR} = \texttt{WH\_INTERIOR} \textbar~\texttt{WH\_GHOSTS}, \texttt{WH\_EVERYWHERE} = \texttt{WH\_INTERIOR} \textbar~\texttt{WH\_EXTERIOR}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Functions Alphabetically}

\begin{Lentry}

\item[\code{Driver\_GetValidRegion}] [\pageref{Driver-GetValidRegion}]
Gets the region where a grid function is valid.

\item[\code{Driver\_NotifyDataModified}] [\pageref{Driver-NotifyDataModified}]
Notify the driver as to which region of which grid function you have updated.

\item[\code{Driver\_RequireValidData}] [\pageref{Driver-RequireValidData}]
Ask the driver to provide valid data in the region you specify.

\item[\code{Driver\_SelectGroupForBC}] [\pageref{Driver-SelectGroupForBC}]
Tell the driver how to update the boundary conditions for the grid functions in a group.

\item[\code{Driver\_SelectVarForBC}] [\pageref{Driver-SelectVarForBC}]
Tell the driver how to update the boundary conditions for a grid functions.

\item[\code{Driver\_SetValidRegion}] [\pageref{Driver-SetValidRegion}]
Sets the region where a grid function is valid.

\end{Lentry}

\begin{FunctionDescription}{Driver\_GetValidRegion}
\label{Driver-GetValidRegion}
% yyy
Gets the region where a grid function is valid.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int where = CCTK_GetValidRegion(int variable_index ,int time_level);

\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{where}
Region where the given grid variable is valid at the given time level.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{variable\_index}
The index of a grid function.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{time\_level}
The time level of a grid function.
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{Driver\_SetValidRegion}{Driver-SetValidRegion}
Sets the region where a grid function is valid.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{Abort}
Assertions may be triggered for invalid variables or time levels.
\end{Error}
\end{ErrorSection}
% zzz
\end{FunctionDescription}

\begin{FunctionDescription}{Driver\_NotifyDataModified}
\label{Driver-NotifyDataModified}
Notify the driver as to which region of which grid function you have updated.
% yyy
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int zero = CCTK_NotifyDataModified(const cGH *cctkGH,
    int *variable_list,
    int *time_level_list,
    int num_variables,
    int *where_list);

\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{zero}
Always returns zero.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH}
Pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{variable\_list}
An array of \texttt{num\_variables} grid function indexes.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{time\_level\_list}
An array of \texttt{num\_variables} time levels.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{num\_variables}
The number of variable index, time level, where tuples.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{where\_list}
An array of \texttt{num\_variables} where specifications describing
where valid data was modified for a given grid function and time level.
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{Driver\_RequireValidData}{Driver-RequireValidData}
Ask the driver to provide valid data in the region you specify.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{Abort}
Assertions may be triggered for invalid variables or time levels.
\end{Error}
\end{ErrorSection}
% zzz
\end{FunctionDescription}

\begin{FunctionDescription}{Driver\_RequireValidData}
\label{Driver-RequireValidData}
% yyy
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int zero = CCTK_RequireValidData(const cGH *cctkGH,
    int *variable_list,
    int *time_level_list,
    int num_variables,
    int *where_list);

\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{zero}
Always returns zero.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH}
Pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{variable\_list}
An array of \texttt{num\_variables} grid function indexes.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{time\_level\_list}
An array of \texttt{num\_variables} time levels.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{num\_variables}
The number of variable index, time level, where tuples.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{where\_list}
An array of \texttt{num\_variables} where specifications describing
where valid data is needed for a given grid function and time level.
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{Driver\_NotifyDataModified}{Driver-NotifyDataModified}
Notify the driver as to which region of which grid function you have updated.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{Abort}
Assertions may be triggered for invalid variables or time levels.
\end{Error}
\end{ErrorSection}
% zzz
\end{FunctionDescription}

\begin{FunctionDescription}{Driver\_SelectGroupForBC}
\label{Driver-SelectGroupForBC}
Tell the driver how to update the boundary conditions for the grid functions in a group.
% yyy
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int err = Driver_SelectGroupForBC(
    const cGH *cctkGH,
    int faces,
    int width,
    int table handle,
    const char *group_name,
    const char *bc_name);

\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{err}
Returns -6 for an invalid group index, -2 for an invalid boundary condition name.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH}
Pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{faces}
The choice of which faces the boundary condition applies to.
Normally, this will be \texttt{CCTK\_ALL\_FACES}. If a different
specification is desired, consult the documentation on the
Boundary thorn.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{width}
The number of zones from the edge filled in by the boundary condition.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{table\_handle}
The table handle holds extra arguments for the boundary condition, if such are needed. Use
-1 (an invalid table handle) for boundary conditions which need no additional arguments.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{where\_list}
An array of \texttt{num\_variables} where specifications describing
where valid data is needed for a given grid function and time level.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{group\_name}
The name of the group of grid functions to which this boundary condition applies.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{bc\_name}
The name of the boundary condition registered physical boundary condition.
See the documentation for \texttt{Boundary\_RegisterPhysicalBC} on the
Boundary thorn.
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{Driver\_SelectVarForBC}{Driver-SelectVarForBC}
Tell the driver how to update the boundary conditions for a grid functions.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{Abort}
Assertions may be triggered for invalid variables or time levels.
\end{Error}
\end{ErrorSection}
% zzz
\end{FunctionDescription}

\begin{FunctionDescription}{Driver\_SelectVarForBC}
\label{Driver-SelectVarForBC}
% yyy
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int err = Driver_SelectVarForBC(
    const cGH *cctkGH,
    int faces,
    int width,
    int table handle,
    const char *var_name,
    const char *bc_name);

\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{err}
Returns -7 for an invalid variable index, -2 for an invalid boundary condition name.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH}
Pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{faces}
The choice of which faces the boundary condition applies to.
Normally, this will be \texttt{CCTK\_ALL\_FACES}. If a different
specification is desired, consult the documentation on the
Boundary thorn.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{width}
The number of zones from the edge filled in by the boundary condition.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{table\_handle}
The table handle holds extra arguments for the boundary condition, if such are needed. Use
-1 (an invalid table handle) for boundary conditions which need no additional arguments.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{where\_list}
An array of \texttt{num\_variables} where specifications describing
where valid data is needed for a given grid function and time level.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{var\_name}
The name of the grid function to which this boundary condition applies.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{bc\_name}
The name of the boundary condition registered physical boundary condition.
See the documentation for \texttt{Boundary\_RegisterPhysicalBC} on the
Boundary thorn.
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{Driver\_SelectVarForBC}{Driver-SelectGroupForBC}
Tell the driver how to update the boundary conditions for the grid functions in a group.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{Abort}
Assertions may be triggered for invalid variables or time levels.
\end{Error}
\end{ErrorSection}
% zzz
\end{FunctionDescription}

\begin{FunctionDescription}{Driver\_SetValidRegion}
\label{Driver-SetValidRegion}
% yyy
Gets the region where a grid function is valid.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

CCTK_SetValidRegion(int variable_index ,int time_level,int where);

\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

%\begin{ResultSection}
%\begin{Result}{where}
%Region where the given grid variable is valid at the given time level.
%\end{Result}
%\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{variable\_index}
The index of a grid function.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{time\_level}
The time level of a grid function.
\end{Parameter}
\end{ParameterSection}

\begin{ParameterSection}
\begin{Parameter}{where}
The new where specification for the variable and time level.
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{Driver\_GetValidRegion}{Driver-GetValidRegion}
Gets the region where a grid function is valid.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{Abort}
Assertions may be triggered for invalid variables or time levels.
\end{Error}
\end{ErrorSection}
% zzz
\end{FunctionDescription}

\end{cactuspart}
