From 25a70e7aa4ba7781bd547b0857117c6b99f97e27 Mon Sep 17 00:00:00 2001 From: allen Date: Thu, 27 Dec 2001 19:11:11 +0000 Subject: Adding more documentation, explaining a little why you want to use the NaNChecker git-svn-id: http://svn.cactuscode.org/arrangements/CactusUtils/NaNChecker/trunk@20 ff385933-4943-42dc-877b-ffc776028de6 --- doc/documentation.tex | 48 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 39 insertions(+), 9 deletions(-) (limited to 'doc') diff --git a/doc/documentation.tex b/doc/documentation.tex index b2153cb..39fb535 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -10,28 +10,58 @@ \abstract{Thorn NaNChecker reports NaN values found in variables.} \section{Purpose} -% -This thorn can be used to analyze CCTK variables of real or complex data type -for NaN (Not-a-Number) and (on availability of {\tt finite(3)}) infinite -values.\\ -It does this by registering a routine at {\bf CCTK\_POSTSTEP} which checks + +The NaNChecker thorn can be used to analyze Cactus grid variables (that is grid +functions, arrays or scalars) of real or complex data type for NaN +(Not-a-Number) and (on availability of {\tt finite(3)}) infinite +values. Grid variables can be periodically checked, or a call can +be inserted into a thorn to check at a specific point. + +This thorn is a utility thorn, designed to be used for debugging and +testing code for uninitialised variables, or for variables which +become corrupted during a simulation, for example following a division +by zero or illegal memory usage. + +On many architectures, uninitialised variables will be given the value +zero, and simulations using such variables will seeming run perfectly +well. However, not only is it dubious programming practise to assume such +behaviour, but also moving to a new machine may well cause pathalogical +problems (for example, with Alpha processors used in Compaq or Cray machines). +It is thus recommended to test codes periodically with the NaNChecker, +and to fix any problems as soon as they are seen. + +\section{Periodic Testing} + +Periodic testing of variables can easily be achieved by adding NaNChecker +to the {\tt ActiveThorns} parameter, and setting the parameters {\tt +NaNChecker::check\_every} and {\tt NaNChecker::check\_vars} to the required +values. (For most testing purposes these can be set to {\tt 1} and {``all''} +respectively). + +The NaNChecker then registers a routine at {\bf CCTK\_POSTSTEP} which checks at every {\tt NanChecker::check\_every} iteration all the variables listed in -{\tt NaNChecker::check\_vars} and -- in case a NaN was found -- performs an +{\tt NaNChecker::check\_vars} and -- in the case a NaN is found -- performs an action as specified in {\tt NaNChecker::action\_if\_found}.\\ Currently these actions can be to \begin{itemize} - \item just print a level 1 warning message telling you where NaNs were found + \item{\tt just\_warn} (the default) + + just print a level 1 warning message telling you where NaNs were found and how many (for grid array variables).\\ For grid arrays it will also print level 2 warnings with the array index (in fortran order) for all NaN elements. You can limit the number of such warnings by setting the {\tt NanChecker::report\_max} parameter. - \item also set the CCTK termination flag so that Cactus will stop the evolution + \item{\tt terminate} + +also set the CCTK termination flag so that Cactus will stop the evolution loop and gracefully terminate at the next time possible (giving you the choice of outputting the data from the last evolution timestep), - \item print the warning message(s) and immediately terminate Cactus + \item{\tt abort} + +print the warning message(s) and immediately terminate Cactus by a call to {\tt CCTK\_Abort()} \end{itemize} -- cgit v1.2.3