path: root/doc/UsersGuide/Infrastructure.tex

\part{Infrastructure Thorn Writer's Guide}

\begin{enumerate}

 \item{} Concepts and Terminology (Overloading and registration of functions)
 \item{} The cGH structure --- what it is and how to use it
 \item{} Extending the cGH structure
 \item{} Querying Group and Variable Information
 \item{} Providing an IO layer
 \item{} Providing a communication layer
 \item{} Doing more --- replacing the rest of the code
 \item{} Appendices
 \begin{itemize}
  \item{} Overloadable Functions in the F***h
  \begin{itemize}
   \item{} Main
   \begin{itemize}
    \item{} {\t int CCTK\_Initialise(tFleshConfig *)}
    \item{} {\t int CCTK\_Evolve(tFleshConfig *)} 
    \item{} {\t int CCTK\_Shutdown(tFleshconfig *)}
    \item{} Defaults
   \end{itemize}
   \item{} IO
   \begin{itemize}
    \item{} {\t int CCTK\_OutputGH(cGH *GH)}
    \item{} {\t int CCTK\_OutputVarAsByMethod(cGH *GH, const char *var,
          const char *method, const char *alias)}
    \item{} Defaults
    \begin{itemize}
     \item{} {\t CCTK\_OutputGH}
     \item{} {\t CCTK\_OutputVarAsByMethod}
    \end{itemize}
   \end{itemize}
   \item{} Comm
   \begin{itemize}
    \item{} {\t int CCTK\_SyncGroup(cGH *GH, const char *group)}
    \item{} {\t int CCTK\_EnableGroupStorage(cGH *GH, const char *group)}
    \item{} {\t int CCTK\_DisableGroupStorage(cGH *GH, const char *group)}
    \item{} {\t int CCTK\_EnableGroupComm(cGH *GH, const char *group)}
    \item{} {\t int CCTK\_DisableGroupComm(cGH *GH, const char *group)}
    \item{} {\t int CCTK\_Barrier(cGH *GH)}
    \item{} {\t int CCTK\_Reduce(cGH *GH, const char *operation, 
            int n\_infields, int n\_outfields,
            int out\_type, void **outarray, ...)}
    \item{} {\t int CCTK\_Interp(cGH *GH, const char *operation, 
            int n\_coords, int n\_infields, int n\_outfields,
            int n\_points, int type, ...)}
    \item{} {\t int CCTK\_ParallelInit(cGH *GH)}
    \item{} {\t int CCTK\_Init(cGH *GH)}
    \item{} {\t int CCTK\_Exit(cGH *GH)}
    \item{} {\t int CCTK\_Abort(cGH *GH)}
    \item{} {\t cGH *CCTK\_SetupGH(tFleshConfig *config, int convergence\_level)}
    \item{} Defaults
    \begin{itemize}
     \item{} {\t CCTK\_SetupGH} 
    \end{itemize}
   \end{itemize}
  \end{itemize}
  \item{} Registerable Functions in the F***h
  \begin{itemize}
   \item{} Main
   \begin{itemize}
    \item{} Defaults
   \end{itemize}
   \item{} IO
   \begin{itemize}
    \item{} Defaults
   \end{itemize}
   \item{} Comm
   \begin{itemize}
    \item{} Defaults
   \end{itemize}
  \end{itemize}
 \end{itemize}
\end{enumerate}

\begin{CCTKroutine}

\CCTKname{CCTK\_EnableGroupStorage}
\CCTKdesc{Assigns storage for all grid variables in a given group.}
\end{CCTKroutine}

\begin{CCTKsyn}
\hfill {\bf C} && int storage = {\t CCTK\_EnableGroupStorage( cGH *GH, const char *group )}\\
\hfill {\bf Fortran} && 
{\t call CCTK\_EnableGroupStorage( storage, GH, group ) }\\
&& CCTK\_POINTER GH \\
&& CCTK\_INTEGER storage\\
&& CCTK\_STRING group 
\end{CCTKsyn}

\begin{CCTKpar}
\hfill {\t storage}&-&integer status code returned by routine:
\\
&&
  \begin{tabular}{ll}
  -1 & error\\
  0 & storage toggled from unassigned to assigned\\
  1 & storage was already assigned
  \end{tabular}
\\
\hfill {\t GH} &-&Pointer to CCTK grid hierachy
\\
\hfill {\t group}&-&character string denoting the group to assign storage to, in the format {\t <implementation>::<group>}
\end{CCTKpar}

\noindent
\begin{tabular}{p{14cm}}
\\{\bf Discussion} \hfill\\
This routine is overloadable in the flesh, and must be provided by a thorn 
(usually by the thorn implementing the driver, 
{\it e.g. } the default unigrid driver {\t packages/pugh}).\\
\end{tabular}

\noindent
\begin{tabular}{p{3cm}cp{11cm}}
&&\\
{\bf Examples} \hfill &&\\
\hfill {\bf C} && storage = {\t CCTK\_EnableGroupStorage(GH,``imp::group'')};
\\
\hfill {\bf Fortran} && call {\t CCTK\_ENABLEGROUPSTORAGE(istorage,GH,``imp::group'')};
\\
&\\
{\bf Errors} \hfill&&
\\
&& {\bf FIXME} here will be stuff like can return CCTK\_ERROR\_STORAGEERROR
\end{tabular}

\section{Group and Variable Utility Routines}

The CCTK provides a number of utility routines for dealing
with groups and variables. 
Each group has a {\it group index} 
and each variable has a {\it variable index}. 

\subsection{Routines supplying group or variable indices}


\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetNumGroups(void);}
\vskip .25cm
Returns the total number of groups in all implementations.


\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetGroupNum(const char *imp, const char *grp);}
\vskip .25cm
Returns the group index given either
\begin{itemize}
\item{} {\t imp = NULL}, {\t grp = <implementation>::<group>}
\item{} {\t imp = <implementation>}, {\t grp = <group>}
\end{itemize}
 
A valided returned group index will lie between 0 and the number of groups
minus one. The routine returns the error codes
\begin{itemize}
\item{} -1 if no group can be found with the given name
\item{} -2 if both arguments were null
\item{} -3 if the first argument was null and the second argument did not have 
           the correct synthax
\item{} -4 if memory allocation failed
\end{itemize} 

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetNumVars(void);}
\vskip .25cm
Returns the total number of variables in all groups.


\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetVarNum(const char *imp, const char *grp, const char *var);}
\vskip .25cm
Returns the variable index given either:
\begin{itemize}
\item{}  {\t imp = NULL}, {\t grp = NULL}, {\t var = <implementation::variable>}
\item{} {\t imp = <implementation>}, {\t grp = NULL}, {\t var = <variable>}
\item{} {\t imp = <implementation>}, {\t grp = <group>}, {\t var = <variable>}
\end{itemize}

A valid returned variable index will lie 
between 0 and the number of variables
minus one. The routine returns the error codes
\begin{itemize}
\item{} -4 if string memory allocation failed
\item{} -3 if the first two arguments were {\t NULL} and the 
           variable name does not contain the implementation
\item{} -2 if the implementation contains no group with
the given group name 
\item{} -1 if there is no variable with the variable name 
in the group
\end{itemize}

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetFirstVarNum(int group);}
\vskip .25cm
Given the global index for a group, this routine returns the 
global index for the first variable in the group, or -1 if
the given group index lies outside the allowed range of
$0 \le {\t group} < {\t CCTK\_GetNumGroups()}$.

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetNumVarsInGroup(int group);}
\vskip .25cm
Given the global index for a group, this routine returns the 
number of variables in the group, or -1 if
the given group index lies outside the allowed range of
$0 \le {\t group} < {\t CCTK\_GetNumGroups()}$.




\subsection{Routines which take indices and return names}

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t char *CCTK\_GetGroupName(int group);}
\vskip .25cm
Given the global index for a group, this routine returns 
the name of the group prepended by the associated implementation,
e.g. {\t implementation::group}. 
If the index is outside the allowed
range of $0 \le {\t group} < {\t CCTK\_GetNumGroups()}$, or 
memory allocation for the returned string fails then {\t NULL}
is returned. Note that the memory for the returned string should
be freed after it is no longer needed.

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t char *CCTK\_GetVarName(int variable);}
\vskip .25cm
Given the global index for a variable, this routine returns 
the name of the variable. If the index is outside the allowed
range of $0 \le {\t variable} < {\t CCTK\_GetNumVars()}$, then {\t NULL}
is returned.

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t char *CCTK\_GetGroupFromVar(int variable);}
\vskip .25cm
Given the global index for a variable, this routine returns 
the name of the group associated with the variable. If there
is no variable associated with this index {\t NULL} is returned.

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t char *CCTK\_GetImplementationFromVar(int variable);}
\vskip .25cm
Given the global index for a variable, this routine returns 
the name of the implementation associated with the variable. If there
is no variable associated with this index {\t NULL} is returned.

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t char *CCTK\_GetFullName(int variable);}
\vskip .25cm
Given the global index for a variable, this routine returns 
the full name of the variable, that is the variable name prepended
by ``<implementation>::''. The routine returns {\t NULL} if there is 
no variable associated with the given index, or if memory allocation
failed. Note that the memory associated with 
the returned string should be freed after use. 





\subsection{Routines concerned with sizes of variables}

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetMaxDim(void);}
\vskip .25cm
Returns the maximum dimension used by any group.


\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_QueryGroupStorage(cGH *GH, const char *group);}
\vskip .25cm
{\bf ROUTINE STILL TO BE WRITTEN !!!!}

Checks if the given group has storage assigned to the arrays 
it contains.


\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_ArrayGroupSize(cGH *GH, const char *group, int direction);}
\vskip .25cm
{\bf ROUTINE STILL TO BE WRITTEN !!!!}

Returns the size of the arrays in a group, in a given direction.





\subsection{Routines concerned with types of variables}

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetGroupData(int group, int *gtype, int *vtype, int *dim, int *n\_variables, int *n\_timelevels);}
\vskip .25cm
Given the index number for a group, on exit the remaining entries 
in the function argument contain the kind of variables held by
the group, the data type of the variables, their dimension, the
number of variables and the number of timelevels. {\bf QUERY: I
don't understand why these are all pointers, I mean how the right 
number gets into the pointer}. The function returns 1, unless the
group index is outside the allowed range, whence it returns 0.
 
\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GTypeNumber(const char *type);}
\vskip .25cm
A group contains variables all with a certain kind,
which can be {\t ``SCALAR''}, {\t ``GF''} or {\t ``ARRAY''}.
Each of these type strings for a group has an associated 
integer index {\t GROUP\_SCALAR}, {\t GROUP\_GF} and {\t GROUP\_ARRAY} (defined in src/include/Groups.h). This routine
returns the type index associated with a type string.
{\bf QUERY: ANY REASON THIS DOESNT RETURN AN ERROR IF IT DOESNT
GET ONE}

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_VTypeNumber(const char *type);}
\vskip .25cm
The data type of variables can be
{\t ``INTEGER''}, {\t ``REAL''}, {\t ``COMPLEX''} or {\t ``CHAR''}.
Each of these data type for a variable has an associated 
integer index {\t VARIABLE\_INTEGER}, {\t VARIABLE\_REAL}, {\t VARIABLE\_COMPLEX}  and {\t VARIABLE\_CHAR} (defined in src/include/Groups.h). 
This routine returns the type index associated with a type string.
{\bf QUERY: ANY REASON THIS DOESNT RETURN AN ERROR IF IT DOESNT
GET ONE}

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetVarGType(int variable);}
\vskip .25cm
Returns an index denoting the group kind for a given global variable 
index. The routine returns -1 if the variable index is outside the
allowed range of $0 \le {\t variable} < {\t CCTK\_GetNumVars()}$.

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetVarVType(int variable);}
\vskip .25cm
Returns an index denoting the variable data type for a given global variable 
index. The routine returns -1 if the variable index is outside the
allowed range of $0 \le {\t variable} < {\t CCTK\_GetNumVars()}$.

\vskip .5cm

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_GetNumTimeLevels(int variable);}
\vskip .25cm
Returns the number of timelevels for a given global variable index.
The routine returns -1 if the variable index is outside the 
allowed range of  $0 \le {\t variable} < {\t CCTK\_GetNumVars()}$.



\subsection{Miscellaneous routines}

\noindent
{\t \#include ``Groups.h''}
\\
\noindent
{\t int CCTK\_DecomposeGroupName(const char *fullname, char **implementation, char **name);}
\vskip .25cm
This routines takes in the string {\t fullname} which should be of the form
{\t <implementation>::<name>}, and on exit {\t implementation} contains a 
pointer to the string {\t ``<implementation>''}, and {\t name} contains a 
pointer to the string {\t ``<name>''}. The routines returns 0 is the string {\t fullname} was
successfully decomposed, 1 is the given string did not contain {\t ::} and 2 
if memory allocation for the new strings failed. The memory for the two 
resulting strings should be freed when no longer needed.


\begin{itemize}
\item{} CCTK\_GetGHExtensionHandle
\item{} CCTK\_GetHandleName
\item{} CCTK\_GetHandle
\item{} CCTK\_GetHandledData
\item{} int CCTK\_SplitString(char **before, char **after, const char *string, const char *sep);
\item{} int CCTK\_Equals(const char *string1, const char *string2);
\item{} int CCTK\_InList(const char *string1, int n\_elements, ...);
\item{} int CCTK\_IntInRange(int inval, const char *range);
\item{} int CCTK\_DoubleInRange(double inval, const char *range);
\item{} int CCTK\_IntInRangeList(int inval, int n\_elements, ...);
\item{} int CCTK\_DoubleInRangeList(double inval, int n\_elements, ...);
\item{} int CCTK\_SetDoubleInRangeList(double *data, const char *value, 
\item{} int CCTK\_SetIntInRangeList(int *data, const char *value, 
\item{} int CCTK\_SetKeywordInRangeList(char **data, const char *value, 
\item{} int CCTK\_SetString(char **data, const char *value);
\item{} int CCTK\_SetLogical(int *data, const char *value);
\end{itemize}