diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/UsersGuide/FunctionReference.tex | 188 | ||||
-rw-r--r-- | doc/UsersGuide/ThornWriters.tex | 57 |
2 files changed, 183 insertions, 62 deletions
diff --git a/doc/UsersGuide/FunctionReference.tex b/doc/UsersGuide/FunctionReference.tex index c191fa7f..59adfd4d 100644 --- a/doc/UsersGuide/FunctionReference.tex +++ b/doc/UsersGuide/FunctionReference.tex @@ -251,11 +251,20 @@ available from C, not all are currently available from Fortran. [\pageref{nProcs}] Get the total number of processors used +\item[CCTK\_OutputGH] + [\pageref{OutputGH}] + +\item[CCTK\_OutputVar] + [\pageref{OutputVar}] + +\item[CCTK\_OutputVarAs] + [\pageref{OutputVarAs}] + \item[CCTK\_OutputVarAsByMethod] [\pageref{OutputVarAsByMethod}] -\item[CCTK\_OutputGH] - [\pageref{OutputGH}] +\item[CCTK\_OutputVarByMethod] + [\pageref{OutputVarByMethod}] \item[CCTK\_ParallelInit] [\pageref{ParallelInit}] @@ -906,28 +915,6 @@ the Cactus scheduler via a thorn's {\tt schedule.ccl} file. % CommOverloadables.c -\begin{CCTKFunc}{CCTK\_Exit}{Exit the code cleanly} -\label{Exit} -\subroutine{int}{integer}{istat} -\argument{cGH *}{CCTK\_POINTER}{cctkGH} -\argument{int}{integer}{value} -\showargs -\begin{params} -\parameter{cctkGH}{pointer to CCTK grid hierarchy} -\parameter{value}{error code} -\end{params} -\begin{discussion} -\end{discussion} -\begin{examples} -\begin{tabular}{@{}p{3cm}cp{11cm}} -\end{tabular} -\end{examples} -\begin{errorcodes} -\end{errorcodes} -\end{CCTKFunc} - - -% CommOverloadables.c \begin{CCTKFunc}{CCTK\_Equals}{Check for string equality} \label{Equals} \function{int}{integer}{istat} @@ -952,32 +939,21 @@ and zero if they differ. \end{errorcodes} \end{CCTKFunc} - - -%%%%% -% FFF -%%%%% - -\begin{CCTKFunc}{CCTK\_FortranString}{Changes a C string into a Fortran string} -\label{FortranString} -\subroutine{int}{integer}{nchar} -\argument{const char *}{character*(*)}{strout} -\argument{const char *}{CCTK\_STRING}{strin} +% CommOverloadables.c +\begin{CCTKFunc}{CCTK\_Exit}{Exit the code cleanly} +\label{Exit} +\subroutine{int}{integer}{istat} +\argument{cGH *}{CCTK\_POINTER}{cctkGH} +\argument{int}{integer}{value} \showargs \begin{params} -\parameter{nchar}{The number of characters in the C string, not counting the null terminator} -\parameter{strout}{The fortran string which on output contains the C string as the first nchar characters} -\parameter{strin}{The (pointer to the) C string containing the null terminator} +\parameter{cctkGH}{pointer to CCTK grid hierarchy} +\parameter{value}{error code} \end{params} \begin{discussion} -String or keyword parameters in Cactus are passed into Fortran routines as -pointers to C strings. This means that they cannot be directly used as Fortran -strings. This routine allows a Fortran string to be created from such a C string. Note that the Fortran string must be defined to have at least the same expected length as the C string. This routine is only callable from Fortran. \end{discussion} \begin{examples} \begin{tabular}{@{}p{3cm}cp{11cm}} -\hfill {\bf Fortran} && \\ -\\ \end{tabular} \end{examples} \begin{errorcodes} @@ -986,6 +962,12 @@ strings. This routine allows a Fortran string to be created from such a C string + +%%%%% +% FFF +%%%%% + + % Groups.c \begin{CCTKFunc}{CCTK\_FirstVarIndex}{Given a group name returns the first variable index in the group} \label{FirstVarIndex} @@ -1038,6 +1020,33 @@ strings. This routine allows a Fortran string to be created from such a C string \end{CCTKFunc} +\begin{CCTKFunc}{CCTK\_FortranString}{Changes a C string into a Fortran string} +\label{FortranString} +\subroutine{int}{integer}{nchar} +\argument{const char *}{character*(*)}{strout} +\argument{const char *}{CCTK\_STRING}{strin} +\showargs +\begin{params} +\parameter{nchar}{The number of characters in the C string, not counting the null terminator} +\parameter{strout}{The fortran string which on output contains the C string as the first nchar characters} +\parameter{strin}{The (pointer to the) C string containing the null terminator} +\end{params} +\begin{discussion} +String or keyword parameters in Cactus are passed into Fortran routines as +pointers to C strings. This means that they cannot be directly used as Fortran +strings. This routine allows a Fortran string to be created from such a C string. Note that the Fortran string must be defined to have at least the same expected length as the C string. This routine is only callable from Fortran. +\end{discussion} +\begin{examples} +\begin{tabular}{@{}p{3cm}cp{11cm}} +\hfill {\bf Fortran} && \\ +\\ +\end{tabular} +\end{examples} +\begin{errorcodes} +\end{errorcodes} +\end{CCTKFunc} + + % Groups.c @@ -1697,6 +1706,36 @@ The group name should be given in the form {\t <implementation>::<group>} % IOOverloadables.h +\begin{CCTKFunc}{CCTK\_OutputVarAs}{} +\label{OutputVarAs} +\subroutine{int}{}{istat} +\argument{cGH *}{}{cctkGH} +\argument{const char *}{character*(*)}{variable} +\argument{const char *}{character*(*)}{alias} +\showargs +\begin{params} +\parameter{istat}{return flag} +\parameter{cctkGH}{pointer to CCTK grid hierarchy} +\parameter{variable}{full name of variable to output} +\parameter{alias}{name to base output file on} +\end{params} +\begin{discussion} +Output a variable {\t variable} looping over all registered methods. +The output should take place if at all possible, +if the appropriate file exists the data is appended, otherwise a new +file is created. Uses {\t alias} as the name of the variable for the purpose +of constructing a filename. +\end{discussion} +\begin{examples} +\begin{tabular}{@{}p{3cm}cp{11cm}} +\end{tabular} +\end{examples} +\begin{errorcodes} +\end{errorcodes} +\end{CCTKFunc} + + +% IOOverloadables.h \begin{CCTKFunc}{CCTK\_OutputVarAsByMethod}{} \label{OutputVarAsByMethod} \subroutine{int}{}{istat} @@ -1706,9 +1745,72 @@ The group name should be given in the form {\t <implementation>::<group>} \argument{const char *}{character*(*)}{alias} \showargs \begin{params} +\parameter{istat}{return flag} +\parameter{cctkGH}{pointer to CCTK grid hierarchy} +\parameter{variable}{full name of variable to output} +\parameter{method}{method to use for output} +\parameter{alias}{name to base output file on} +\end{params} +\begin{discussion} +Output a variable {\t variable} using the method {\t method} if it is +registered. Uses {\t alias} as the name of the variable for the purpose +of constructing a filename. The output should take place if at all possible, +if the appropriate file exists the data is appended, otherwise a new +file is created. +\end{discussion} +\begin{examples} +\begin{tabular}{@{}p{3cm}cp{11cm}} +\end{tabular} +\end{examples} +\begin{errorcodes} +\end{errorcodes} +\end{CCTKFunc} + +% IOOverloadables.h +\begin{CCTKFunc}{CCTK\_OutputVarByMethod}{} +\label{OutputVarAsMethod} +\subroutine{int}{}{istat} +\argument{cGH *}{}{cctkGH} +\argument{const char *}{character*(*)}{variable} +\argument{const char *}{character*(*)}{method} +\showargs +\begin{params} +\parameter{istat}{return flag} +\parameter{cctkGH}{pointer to CCTK grid hierarchy} +\parameter{variable}{full name of variable to output} +\parameter{method}{method to use for output} +\end{params} +\begin{discussion} +Output a variable {\t variable} using the method {\t method} if it is +registered. The output should take place if at all possible, +if the appropriate file exists the data is appended, otherwise a new +file is created. +\end{discussion} +\begin{examples} +\begin{tabular}{@{}p{3cm}cp{11cm}} +\end{tabular} +\end{examples} +\begin{errorcodes} +\end{errorcodes} +\end{CCTKFunc} + +% IOOverloadables.h +\begin{CCTKFunc}{CCTK\_OutputVar}{} +\label{OutputVar} +\subroutine{int}{}{istat} +\argument{cGH *}{}{cctkGH} +\argument{const char *}{character*(*)}{variable} +\showargs +\begin{params} +\parameter{istat}{return flag} \parameter{cctkGH}{pointer to CCTK grid hierarchy} +\parameter{variable}{full name of variable to output} \end{params} \begin{discussion} +Output a variable {\t variable} looping over all registered methods. +The output should take place if at all possible, +if the appropriate file exists the data is appended, otherwise a new +file is created. \end{discussion} \begin{examples} \begin{tabular}{@{}p{3cm}cp{11cm}} diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex index eda5422b..c1210165 100644 --- a/doc/UsersGuide/ThornWriters.tex +++ b/doc/UsersGuide/ThornWriters.tex @@ -428,29 +428,38 @@ changes the access level for any parameter defined in the file from that point o To access {\tt restricted} parameters from another implementation, a line containing {\tt shares: <name>} declares that all parameters mentioned in the file from now until the next access specification originate in -implementation {\tt <name>}. +implementation {\tt <name>}. Each of these parameters must be qualified by the initial token {\tt USES} or {\tt EXTENDS}, where +\begin{Lentry} +\item[{\tt USES}] indicates that the parameters range remains unchanged. +\item[{\tt EXTENDS}] indicates that the parameters range is going to be extended. +\end{Lentry} In contrast to parameter declarations in other access blocks, the default value must be omitted - it is impossible to set the default value of any parameter not originating in this thorn. For example, the following block adds possible values to the keyword -{\tt initial\_data} originally defined in the implementation {\tt einstein}. +{\tt initial\_data} originally defined in the implementation {\tt einstein}, +and uses the real parameter {\tt speed}. \begin{verbatim} - shares:einstein -KEYWORD initial_data "" +EXTENDS KEYWORD initial_data "" { "bl_bh" :: "Brill Lindquist black holes" "misner_bh" :: "Misner black holes" "schwarzschild" :: "One Schwarzschild black hole" } +USES CCTK_REAL speed "" +{ +} + \end{verbatim} Note that you must compile at least one thorn which implements {\tt einstein}. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1360,7 +1369,9 @@ the global grid. \item {\tt cctk\_bbox} An array of 2*{\tt cctk\_dim} integers which indicate whether the boundaries are internal boundaries - (e.g. between processors), or physical boundaries. + (e.g. between processors), or physical boundaries. A value of 1 indicates + a physical (outer) boundary at the edge of the computational grid, + and 0 indicates an internal boundary. \end{itemize} The following variable is needed for grid refinement methods @@ -1994,43 +2005,51 @@ file is created. A reduction operation can be defined as an operation on variables distributed across multiple processor resulting in a single number. Typical reduction operations are: sum, minimum/maximum value, boolean -operations. A typical applications is e.g. the maximum reduction on -a processor local error estimates, therefor making the previous -processor local error known to all processors. +operations. A typical application is, for example, +finding the maximum reduction from processor local error estimates, +therefor making the previous processor local error known to all processors. The exchange of information across processors needs the functionality of a -communication layer eg. PUGH. For this reason, the +communication layer eg. {\tt CactusPUGH/PUGH}. For this reason, the reduction operation itself is not part of the flesh, instead Cactus (again) provides a registration mechanism for thorns to register routines they provide as reduction operators. The different operators are -identified by their name and a unique number, called a {\em handle}. +identified by their name and/or a unique number, called a {\em handle}. The registration mechanism gives the advantage of a common interface while hiding the individual communication calls in the layer. -In Cactus, reduction operators can be applied to gridfunctions, grid -scalars and distributed arrays, as well as local variables/arrays. +In Cactus, reduction operators can in principle be applied to +grid functions, arrays and scalars, as well as to local arrays. Note that +different implementations of reduction operators may be limited in +the objects they can be applied to. There is a fundamental difference between the reduction operation on grid functions and quantities as arrays. +\vskip .25cm {\bf Obtaining the reduction handle} + Before calling the routine which performs the reduction operation, the handle, which indentifies the operation must be derived from its registered name. \begin{verbatim} -int CCTK_GetReductionHandle(const char *reduction_name); +int CCTK_ReductionHandle(const char *reduction_name); -call CCTK_ReductionHandle(int reduction_handle, character reduction_name) +integer reduction_handle +character*(*) reduction_name +call CCTK_ReductionHandle(reduction_handle, reduction_name) int CCTK_GetReductionArrayHandle(const char *reduction_name); -call CCTK_ReductionArrayHandle(int reduction_handle, character reduction_name) +integer reduction_handle +character*(*) reduction_name +call CCTK_ReductionArrayHandle(reduction_handle, reduction_name) \end{verbatim} @@ -2044,12 +2063,12 @@ contain the handle value after the call. In C this value is the function value. \item[{\tt reduction\_name}] is the name under which the operator has -been registered by the providind thorn. Currently only PUGH is -providing reduction operations. +been registered by the providing thorn. The only thorn in the standard +Computational Toolkit release which provides reduction operators is +{\tt CactusPUGH/PUGHReduce}. \item[{\bf error checking}] negative handle value indicates failure to -identify the correct operator. Possible causes: misspelled operator -name, operator not registered properly. +identify the correct operator. \end{Lentry} Get a integer handle corresponding to a given reduction operator. |