From c5aa3be5658ef1be8a97b2856afcf89a0b9b3446 Mon Sep 17 00:00:00 2001 From: swhite Date: Tue, 10 Aug 2004 14:28:59 +0000 Subject: Added to glossary: domain decomposition, function aliasing git-svn-id: http://svn.cactuscode.org/flesh/trunk@3824 17b73243-c579-4c4c-a9d2-2d5706c11dac --- doc/UsersGuide/Appendices.tex | 10 +++ doc/UsersGuide/ThornWriters.tex | 192 ++++++++++++++++++++++------------------ 2 files changed, 115 insertions(+), 87 deletions(-) diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex index 4ee2b3de..135b93b6 100644 --- a/doc/UsersGuide/Appendices.tex +++ b/doc/UsersGuide/Appendices.tex @@ -25,6 +25,7 @@ Cactus Users' Guide and the Cactus Reference Manual. \begin{Lentry} \item[alias function] + See \textit{function aliasing}. \item[AMR] \textit{Automatic Mesh Refinement} \item[analysis] @@ -94,6 +95,9 @@ Cactus Users' Guide and the Cactus Reference Manual. distribution system for Cactus. See Sections~\ref{sec:checkout}, \ref{sec:Appendix.cvs}. \item[domain decomposition] + The technique of breaking up a large computational problem into parts + that are easier to solve. In Cactus, refers especially to a decomposition + wherein the parts are solved in parallel on separate computer processors. \item[driver] A special kind of thorn which creates and handles grid hierarchies and grid variables. @@ -110,6 +114,11 @@ Cactus Users' Guide and the Cactus Reference Manual. set of protected grid variables. See Section~\ref{subsec:interface_ccl}. \ref{sec:Appendix.interface}. \item[function aliasing] + The process of referring to a function to be provided by an interface + independently of which thorn actually contains the function, or what + language the function is written in. The function is called an + \textit{alias function}. See Section~\ref{sec:function_aliasing}, + \ref{subsec:Appendix.interface.function_aliasing}. \item[GA] Shorthand for a \textit{grid array}. \item[GF] @@ -429,6 +438,7 @@ only executed if the providing thorn is active. Both default to \verb|HEADER|. \subsection{Function aliasing} +\label{subsec:Appendix.interface.function_aliasing} If any aliased function is to be used or provided by the thorn then the prototype must be declared with the form: \begin{alltt} diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex index cd4f8aa3..7a4c6021 100644 --- a/doc/UsersGuide/ThornWriters.tex +++ b/doc/UsersGuide/ThornWriters.tex @@ -915,6 +915,7 @@ quickly with a lower accuracy. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Group Types} +\label{sec:cactus_variables-groups} Groups can be either \textit{scalars}, \textit{grid functions} (GFs), or \textit{grid arrays}. Different attributes are relevant for the different group @@ -3441,15 +3442,18 @@ You can add any number of timers to your thorn source code, providing each with a name of your choice, and then use Cactus timing functions to switch on the timers, stop or reset them, and recover timing information. +Setting the Flesh parameter \texttt{cactus::cctk\_timer\_output = "full"} +will cause some summary timing information to be printed at the end of a run. +Some other thorns have their own timer printing parameters as well. + \subsection{Timing calls} Many of the timing calls come in two versions, one whose name ends with -the letter \texttt{I} and another one. The calls whose names end in the -letter \texttt{I} refer to the timer by index, -wich is a non-negative \texttt{int} value; the other calls -refer to a timer by name. If a timer is created without a name, it can -be referred to only by its index, otherwise, it can be referred to by name -or by index. +the letter \texttt{I} and one without. The calls whose names end with the +letter \texttt{I} refer to the timer or clock by index, which is a +non-negative \texttt{int} value; the other calls refer to a timer by name. +If a timer is created without a name, it can be referred to only by its index, +otherwise, it can be referred to by name or by index. Typically, a negative return value from a timer function indicates an error. @@ -3465,7 +3469,7 @@ Only one timer with a given name can exist at any given time. \item[{\t CCTK\_TimerDestroy}, {\t CCTK\_TimerDestroyI}] -Destroy a timer. +Reclaim resources used by a timer. \item[{\t CCTK\_TimerStart}, {\t CCTK\_TimerStartI}] @@ -3479,13 +3483,15 @@ Stop the given timer on all registered clocks. Reset the given timer on all registered clocks. -\item[{\t CCTK\_TimerCreateData}, {\t CCTK\_Timer}, {\t CCTK\_TimerI}, {\t CCTK\_TimerDestroyData}] +\item[{\t CCTK\_TimerCreateData}, {\t CCTK\_TimerDestroyData}] + +Allocate and reclaim (respectively) resources for a {\t cTimerData} structure, +which will be used to hold clock values. -Access the actual timing results, which are passed back as a -structure, {\t cTimerData} described below, in {\t CCTK\_Timer}. -Since the timing data is dynamic, before it can be assessed, the structure -must be allocated with a call to {\t CCTK\_TimerCreateData}. A similar function -is provided to destroy the structure +\item[{\t CCTK\_Timer}, {\t CCTK\_TimerI}] + +Fill the given {\t cTimerData} structure with clock values as of +the last call to {\t CCTK\_TimerStop}. \item[{\t CCTK\_NumTimers}] @@ -3494,46 +3500,66 @@ Return the number of created timers \item[{\t CCTK\_TimerName}] Return the name of the timer for a given timer index (or {\t NULL} if -the timer is unnamed or any other error occurs. +the timer is unnamed or any other error occurs). -\end{Lentry} +\item[{\t CCTK\_NumTimerClocks}] -\subsection{The {\tt cTimerData} Structure} -\label{subsec:cTimerData} +Take a pointer to {\t cTimerData} and return the number of clocks +recorded in a timer measurement -The structure holding the timing data, {\tt cTimerData}, contains -the number of collected times (one measurement for each registered clock), -and the measured time for each clock. The measured time is held in -a structure of type {\tt cTimerVal} which contains the data type -of the measured value, a description of the clock, and the units used -for the measurements. Hopefully additional interfaces will soon be added -to avoid detailed knowledge of these structures, but for now here are -the gory details: +\item[{\t CCTK\_GetClockValue}, {\t CCTK\_GetClockValueI}] -{\tt -\begin{verbatim} -typedef enum {val_none, val_int, val_long, val_double} cTimerValType; +Given a clock referred to by name or index, respectively, and a +{\t cTimerData} pointer, return a {\t cTimerVal} pointer representing +the value of the clock when the timer was stopped -typedef struct -{ - cTimerValType type; - const char *heading; - const char *units; - union - { - int i; - long int l; - double d; - } val; -} cTimerVal; +\item[{\t CCTK\_TimerClockName}] -typedef struct -{ - int n_vals; - cTimerVal *vals; -} cTimerData; -\end{verbatim} -} +Return the name of the clock given by the {\t cTimerVal} pointer argument. + +\item[{\t CCTK\_TimerClockSeconds}] + +Return the floating-point value of the measurement in seconds +from the {\t cTimerVal} pointer argument. + +\end{Lentry} + +%\subsection{The {\tt cTimerData} Structure} +%\label{subsec:cTimerData} +% +%The structure holding the timing data, {\tt cTimerData}, contains +%the number of collected times (one measurement for each registered clock), +%and the measured time for each clock. The measured time is held in +%a structure of type {\tt cTimerVal} which contains the data type +%of the measured value, a description of the clock, and the units used +%for the measurements. Hopefully additional interfaces will soon be added +%to avoid detailed knowledge of these structures, but for now here are +%the gory details: +% +%{\tt +%\begin{verbatim} +%typedef enum {val_none, val_int, val_long, val_double} cTimerValType; +% +%typedef struct +%{ +% cTimerValType type; +% const char *heading; +% const char *units; +%% union + { +% int i; +% long int l; +% double d; +% } val; +%} cTimerVal; +% +%typedef struct +%{ +% int n_vals; +% cTimerVal *vals; +%} cTimerData; +%\end{verbatim} +%} \subsection{How to insert timers in your code} @@ -3542,15 +3568,15 @@ include file {\tt cctk\_Timers.h}, which is included in the standard thorn header file {\tt cctk.h}. At the moment the timer calls are only available from C. -The following example, which uses a timer called {\t TimeMyStuff} to +The following example, which uses a timer to instrument a section of code, illustrates how timers are used by -application thorns. A working example is available in the thorn {\tt -CactusTest/TestTimers}. +application thorns. A working example is available in the thorn +{\tt CactusTest/TestTimers}. -{\bf Creating the {\t TimeMyStuff} timer} +{\bf Creating a timer} The first action for any timer is to create it, using -\texttt{ CCTK\_TimerCreate}. +\texttt{CCTK\_TimerCreate}. This can be performed at any time prior to use of the timer: \begin{verbatim} @@ -3563,50 +3589,41 @@ index = CCTK_TimerCreate("TimeMyStuff"); Code sections are instrumented using the Start, Stop and Reset functions. These functions are applied to the chosen timer using all the registered clocks. \begin{verbatim} -#include "cctk_Timers.h" ierr = CCTK_TimerStart("TimeMyStuff"); -/* Piece of code to time */ -y = CalculateNewValue(y); +do_procedure_to_be_timed(); ierr = CCTK_TimerStop("TimeMyStuff"); \end{verbatim} {\bf Accessing the timer results} -This is a little bit cumbersome at the moment, since the timer data can be -of different types. +After calling {\t CCTK\_TimerStop}, you then get the time value from +any of the registered clocks. + +The procedure is to allocate a {\t cTimerData} structure, +and read the information from your timer into this structure +using {\t CCTK\_Timer}, then to extract time data of the desired clock from +this structure. After using the structure, you should destroy it. \begin{verbatim} -#include "cctk_Timers.h" -cTimerData *info; + cTimerData *info = CCTK_TimerCreateData(); + ing ierr = CCTK_Timer("TimeMyStuff",info); + + /* You can refer to a particular clock by name. */ + const cTimerVal *clock = CCTK_GetClockValue( "gettimeofday", info ); + if( clock ){ + printf ("\t%s: %.3f %s\n", "gettimeofday", + CCTK_TimerClockSeconds( clock ), "secs" ); + } -info = CCTK_TimerCreateData(); -ierr = CCTK_Timer("TimeMyStuff",info); + /* To get results from all available clocks, refer to them by index.*/ + nclocks = CCTK_NumTimerClocks( info ); -for (i = 0; i < info->n_vals; i++) -{ - switch (info->vals[i].type) - { - case val_int: - printf("%s: %d %s", info->vals[i].heading,info->vals[i].val.i, - info->vals[i].units); - break; - - case val_long: - printf("%s: %d %s", info->vals[i].heading,(int) info->vals[i].val.l, - info->vals[i].units); - break; - - case val_double: - printf("%s: %.3f %s", info->vals[i].heading,info->vals[i].val.d, - info->vals[i].units); - break; - - default: - CCTK_WARN(1, "Unknown data type for timer info"); - break; + for (i = 0; i < numclocks; i++) { + const cTimerVal *clock = CCTK_GetClockValueI( i, info ); + printf ("\t%s: %.3f %s\n", CCTK_TimerClockName( clock ), + CCTK_TimerClockSeconds( clock ), "secs" ); } -} -ierr = CCTK_TimerDestroyData(info); + CCTK_TimerDestroyData (info); \end{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3992,6 +4009,7 @@ strings from C. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Function aliasing} +\label{sec:function_aliasing} As well as calling functions in a different language, Cactus offers a mechanism for calling a function in a different thorn where you need @@ -4016,8 +4034,8 @@ declarations. \subsection{Using an aliased function} -To use an aliased function you must first declare it in your {\tt -interface.ccl} file. Declare the prototype as, for example, +To use an aliased function you must first declare it in your +\tt{ interface.ccl} file. Declare the prototype as, for example, \begin{verbatim} CCTK_REAL FUNCTION SumStuff(CCTK_REAL IN x, CCTK_REAL IN y) \end{verbatim} -- cgit v1.2.3