1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
\documentclass{article}
% Use the Cactus ThornGuide style file
% (Automatically used from Cactus distribution, if you have a
% thorn without the Cactus Flesh download this from the Cactus
% homepage at www.cactuscode.org)
\usepackage{../../../../doc/ThornGuide/cactus}
\begin{document}
\title{NaNChecker}
\author{Thomas Radke}
\date{$ $Date$ $}
\maketitle
% Do not delete next line
% START CACTUS THORNGUIDE
\begin{abstract}
Thorn NaNChecker reports NaN values found in CCTK grid variables.
\end{abstract}
% Do not delete next line
% END CACTUS THORNGUIDE
\section{Purpose}
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 seemingly 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
\noindent
{\tt NaNChecker::check\_every, NaNChecker::check\_after,} and {\tt NaNChecker::check\_vars}
\noindent
to the required
values. (For most testing purposes these can be set to {\tt 1, 0,} and {"all"}
respectively).
The NaNChecker then registers a routine at {\bf CCTK\_POSTSTEP} which checks
at every {\tt NanChecker::check\_every} iteration -- starting at iteration
number {\tt NaNChecker::check\_after} -- all the variables listed in
{\tt NaNChecker::check\_vars} for NaN or infinite values (depending on {\tt
NaNChecker::check\_for}) and --- if such a value is found --- performs an
action as specified in {\tt NaNChecker::action\_if\_found}.\\
Currently these actions can be to
\begin{itemize}
\item{\tt just\_warn} (the default)
just print a level 1 warning message telling you where NaNs/Infs were found
and how many (for grid array variables).\\
For grid arrays it will also print information with the array index
(in fortran order) for all NaN/Inf elements, depending on the value of
the keyword parameter {\tt verbose}. You can limit the number of
such warnings by setting the {\tt NanChecker::report\_max} parameter.
\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{\tt abort}
print the warning message(s) and immediately terminate Cactus after checking
all variables from {\tt NaNChecker::check\_vars} by a call to {\tt CCTK\_Abort()}
\end{itemize}
By default, the current timelevel of the variables given in
{\tt NaNChecker::check\_vars} will be checked. This can be overwritten by
an optional string {\tt [timelevel=<timelevel>]} appended to the
variable/group name. For example, to apply the NaNChecker to timelevel 0
of the variable grid::x, timelevel 1 of {\tt grid::y} and timelevel 2 of
{\tt grid::z} you would use the parameter
\noindent
{\tt NaNChecker::check\_vars = "grid::x grid::y[timelevel=1] grid::z[timelevel=2]"}
%
\section{Tracking and Visualizing NaNs Positions}
%
The NaNChecker thorn can also mark the positions (in grid index points)
of all the NaNs found for a given list of CCTK grid functions in a mask array
and save this array to an HDF5 file.
The mask array is declared as a grid function {\tt NaNChecker::NaNmask} with
data type INTEGER. Each bit $i$ in an integer element is used to flag a NaN
value found in grid function $i$ at the corresponding grid position
(the counting for $i$ starts at 0 and is incremented for each grid function
as it appears in {\tt NaNChecker::check\_vars}).
Thus the NaN locations of up to 32 individual grid functions can be coded
in the NaNmask array.
In order to activate the NaNmask output you need to set the parameter
{\tt NaNChecker::out\_NaNmask} to {\tt "yes"} (which is already the default)
and have the IOHDF5 thorn activated.
The NaN locations can be visualized with OpenDX. An example DX network
{\tt VisualizeNaNs.net} and a sample NaNmask HDF5 output file {\tt NaNmask.h5}
are available via anonymous CVS from the NumRel CVS server:
\begin{verbatim}
# this is for (t)csh; use export CVSROOT for bash
setenv CVSROOT :pserver:cvs_anon@cvs.aei.mpg.de:/numrelcvs
# CVS pserver password is 'anon'
cvs login
cvs checkout AEIPhysics/Visualization/OpenDX/Networks/Miscellaneous
\end{verbatim}
%
\section{NaNChecker API}
%
Thorn NaNChecker also provides a function API which can be used by other code
to invoke the NaNChecker routines to test for NaN/Inf values or to set NaN
values for a list of variables:
\vskip .2cm
\noindent{\bf C API}
\begin{verbatim}
int NaNChecker_CheckVarsForNaN (const cGH *cctkGH,
int report_max,
const char *vars,
const char *check_for,
const char *action_if_found);
int NaNChecker_SetVarsToNaN (const cGH *cctkGH,
const char *vars);
\end{verbatim}
\vskip.2cm
\noindent
{\bf Fortran API}
\begin{verbatim}
call NaNChecker_CheckVarsForNaN (ierror, cctkGH, report_max,
vars, check_for, action_if_found)
integer ierror
CCTK_POINTER cctkGH
integer report_max
character*(*) vars
character*(*) check_for
character*(*) action_if_found
call NaNChecker_SetVarsToNaN (ierror, cctkGH, vars)
integer ierror
CCTK_POINTER cctkGH
character*(*) vars
\end{verbatim}
The {\tt report\_max, check\_vars, check\_for} and {\tt action\_if\_found}
arguments have the same semantics as their parameter counterparts.\\
If {\tt action\_if\_found} is given as a NULL pointer (C API) or as an empty
string (Fortran API) the routine will be quiet and just return the number of
NaN values found.\\
The C function {\tt NaNChecker\_CheckVarsForNaN()} returns the total number of
NaN/Inf values found, {\tt NaNChecker\_SetToNaN()} returns the total number of
variables set to NaN; this return value is stored in the {\tt ierror} argument
for the corresponding fortran wrapper routines.
% Do not delete next line
% END CACTUS THORNGUIDE
\end{document}
|
