diff options
Diffstat (limited to 'doc/UsersGuide/Infrastructure.tex')
-rw-r--r-- | doc/UsersGuide/Infrastructure.tex | 419 |
1 files changed, 0 insertions, 419 deletions
diff --git a/doc/UsersGuide/Infrastructure.tex b/doc/UsersGuide/Infrastructure.tex index 5bf9bf41..3d3babf0 100644 --- a/doc/UsersGuide/Infrastructure.tex +++ b/doc/UsersGuide/Infrastructure.tex @@ -77,424 +77,5 @@ -\begin{CCTKFunc}{CCTK\_EnableGroupStorage} -{Assigns storage for all grid variables in a given group.} -\function{int}{CCTK\_INT}{storage} -\argument{cGH *}{CCTK\_INT}{GH} -\argument{const char *}{CCTK\_STRING}{group} -\showargs -\begin{params} -\parameter{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} -} -\end{params} -\begin{discussion} -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{discussion} -\begin{examples} -\begin{tabular}{@{}p{3cm}cp{11cm}} -\hfill {\bf C} && storage = {\t CCTK\_EnableGroupStorage(GH,``imp::group'')}; -\\ -\hfill {\bf Fortran} && call {\t CCTK\_ENABLEGROUPSTORAGE(istorage,GH,``imp::group'')}; -\\ -\end{tabular} -\end{examples} -\begin{errorcodes} -\errorcode{FIXME:CCTK\_NOSUCHVARIABLE}{The variable doesn't exist} -\end{errorcodes} -\end{CCTKFunc} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\begin{CCTKroutine} -\CCTKname{CCTK\_RegisterReductionOperator} -\CCTKdesc{Registers a function as providing a CCTK reduction operator with a given name} -\end{CCTKroutine} - -\begin{CCTKsyn} -\hfill {\bf C} && {\t int handle = CCTK\_RegisterReductionOperator(void (*function)(cGH *, int, int, int, void *, int, int *), const char *name)} -\\ -\hfill {\bf Fortran} && Not available. Use a C wrapper function. -\end{CCTKsyn} - -\begin{CCTKpar} -\hfill {\t handle}&-&integer returning the handle for the function or an error code. -\\ -\hfill {\t function}&-&pointer to the reduction operator. -\\ -\hfill {\t name}&-&the name with which the reduction operator should be called. -\end{CCTKpar} - -\noindent -\begin{tabular}{p{14cm}} -\\ -{\bf Discussion} \hfill -\\ -\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} - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \end{cactuspart} |