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
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
\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/latex/cactus}
\begin{document}
\title{IOBasic}
\author{Gabrielle Allen \\ Thomas Radke}
\date{$ $Date$ $}
\maketitle
% Do not delete next line
% START CACTUS THORNGUIDE
\begin{abstract}
Thorn {\bf IOBasic} provides I/O methods for outputting scalar values in
ASCII format into files and for printing them as runtime information to screen.
\end{abstract}
\section{Purpose}
Thorn {\bf IOBasic} registers 2 I/O methods with the I/O interface in the flesh
which both output the same following information:
%
\begin{itemize}
\item for CCTK\_SCALAR variables, the value of the scalar versus time
\item for CCTK\_GF and CCTK\_ARRAY variables, the values of global reduction
operations (eg. minimum, maximum, L1, and L2 norm) versus time
\end{itemize}
%
The I/O methods differ in the destination the output is written to:
\begin{itemize}
\item{\tt Scalar}\\
This method outputs the information into ASCII files named {\tt "<scalar\_name>.\{asc|xg\}"} (for CCTK\_SCALAR variables) and {\tt "<var\_name>\_<reduction>.\{asc|xg\}"}
(for CCTK\_GF and CCTK\_ARRAY variables where {\tt reduction} would stand
for the type of reduction value that is output).\\
The output data can be plotted by using either {\it xgraph} (for {\tt "*.xg"} files) or
{\it gnuplot} (for {\tt "*.asc"} files). The output style can be selected via parameter settings.
\item {\tt Info}\\
This method prints the data as runtime information to {\it stdout}.\\
The output occurs as a table with columns containing the current iteration
number, the physical time at this iteration, and more columns for
scalar/reduction values of each variable to be output.\\
\end{itemize}
%
%
\section{{\bf IOBasic} Parameters}
%
Parameters to control the {\tt Scalar} I/O method are:
\begin{itemize}
\item {\tt IOBasic::outScalar\_criterion} (steerable)\\
The criterion that decides when to {\tt Scalar} output. If
this parameter is set in the parameter file, it will override
the setting of the shared {\tt IO::out\_criterion} parameter.
\item {\tt IOBasic::outScalar\_every} (steerable)\\
How often, in terms of iterations, to do {\tt Scalar} output.
If this parameter is set in the
parameter file, it will override the setting of the shared
{\tt IO::out\_every} parameter.
\item {\tt IOBasic::outScalar\_dt} (steerable)\\
How often, in terms of simulation time, to do {\tt Scalar}
output. If this parameter is set in the parameter file, it
will override the setting of the shared {\tt IO::out\_dt}
parameter.
\item {\tt IOBasic::out\_dir}\\
The directory in which to place the {\tt Scalar} ASCII output files.
If the directory doesn't exist at startup it will be created.\\
If this paraeter is set to an empty string {\tt Scalar} output will go
to the standard output directory as specified in {\tt IO::out\_dir}.
\item {\tt IOBasic::outScalar\_style}\\
How to start comments in the {\tt Scalar} ASCII output files.\\
Possible choices for this keywork parameter are {\it xgraph} and
{\it gnuplot}.
\item {\tt IOBasic::out\_format} (steerable)\\
The output format for floating-point numbers in {\tt Scalar} output.\\
This parameter conforms to the format modifier of the C library routine
{\it fprintf(3)}. You can set the format for outputting floating-point
numbers (fixed or exponential) as well as their precision (number of
digits).
\item {\tt IOBasic::outScalar\_vars} (steerable)\\
The list of variables to output into individual ASCII files.\\
The variables must be given by their fully qualified variable or group
name. The special keyword {\it all} requests {\tt Scalar}
output for all
variables. Multiple variables must be separated by spaces.
For CCTK\_GF and CCTK\_ARRAY variables, an option string can
be appended
in curly braces to the name of the variable. The only option
supported so far is an individual list of reductions for that variable
which would take precedence over the default reduction operations to
perform.
\item {\tt IOBasic::outScalar\_reductions} (steerable)\\
The list of global reduction operations to perform on
CCTK\_GF and CCTK\_ARRAY variables for {\tt Scalar} output.
This setting can be overridden for individual variables using an
option string.\\
Multiple reduction names must be separated by spaces.
\end{itemize}
%
%
Parameters to control the {\tt Info} I/O method are:
\begin{itemize}
\item {\tt IOBasic::outInfo\_criterion} (steerable)\\
The criterion that decides when to {\tt Info} output. If
this parameter is set in the parameter file, it will override
the setting of the shared {\tt IO::out\_criterion} parameter.
\item {\tt IOBasic::outInfo\_every} (steerable)\\
How often, in terms of iterations, to do {\tt Info} output.
If this parameter is set in the
parameter file, it will override the setting of the shared
{\tt IO::out\_every} parameter.
\item {\tt IOBasic::outInfo\_dt} (steerable)\\
How often, in terms of simulation time, to do {\tt Info}
output. If this parameter is set in the parameter file, it
will override the setting of the shared {\tt IO::out\_dt}
parameter.
\item {\tt IOBasic::outInfo\_vars} (steerable)\\
The list of variables to output to screen.\\
The variables must be given by their fully qualified variable or group
name. The special keyword {\it all} requests {\tt Info} output for all
variables. Multiple variables must be separated by spaces.\\
For CCTK\_GF and CCTK\_ARRAY variables, an option string can
be appended
in curly braces to the name of the variable. The only option
supported so far is an individual list of reductions for that variable
which would take precedence over the default reduction operations to
perform.
\item {\tt IOBasic::outInfo\_reductions} (steerable)\\
The default list of global reduction operations to perform on
CCTK\_GF and CCTK\_ARRAY variables. This setting can be overridden
for individual variables using an option string.\\
Multiple reduction names must be separated by spaces.
\end{itemize}
All of the above parameters marked as steerable can be changed at runtime.
%
%
\section{Examples}
%
\subsection {Example for {\tt Info} Output}
%
The following parameter settings request info output for variables {\tt
grid::r, wavetoy::phi} (both are CCTK grid functions) and {\tt
mythorn::complex}
(a complex CCTK scalar) at every other iteration.
The minimum and maximum of {\tt grid::r} is printed according to the list
of default reductions for info output (parameter {\tt
IOBasic::outInfo\_reductions}). This list is overridden for {\tt
wavetoy::phi} where only the L2 norm
is output as specified in the option string for this variable. You can also
add other reduction operators within the $\{\}$ braces.
For the scalar variable {\tt mythorn::complex} both the real and
imaginary part are printed.
\begin{verbatim}
IOBasic::outInfo_every = 2
IOBasic::outInfo_vars = "grid::r
wavetoy::phi{reductions = 'norm2'}
mythorn::complex"
IOBasic::outInfo_reductions = "minimum maximum"
\end{verbatim}
The resulting screen output would look like this:
\begin{verbatim}
---------------------------------------------------------------------------------------------
it | | GRID::r | WAVETOY::phi | MYTHORN::complex |
| t | minimum | maximum | norm2 | real part | imag part |
---------------------------------------------------------------------------------------------
0 | 0.000 | 0.02986294 | 0.86602540 | 0.04217014 | 6.90359593 | 0.00000000 |
2 | 0.034 | 0.02986294 | 0.86602540 | 0.00934749 | 6.90359593 | 0.00000000 |
4 | 0.069 | 0.02986294 | 0.86602540 | 0.02989811 | 6.90359593 | 0.00000000 |
6 | 0.103 | 0.02986294 | 0.86602540 | 0.05899959 | 6.90359593 | 0.00000000 |
8 | 0.138 | 0.02986294 | 0.86602540 | 0.07351147 | 6.90359593 | 0.00000000 |
10 | 0.172 | 0.02986294 | 0.86602540 | 0.07781795 | 6.90359593 | 0.00000000 |
\end{verbatim}
%
\subsection {Example for {\tt Scalar} Output}
%
The following parameter settings request scalar output for all grid function
variables in the group {\tt grid::coordinates} and for the scalar variable
{\tt grid::coarse\_dx}.\\
Output occurs every 10th iteration. {\tt gnuplot} output style is selected
for the ASCII files which are placed into a subdirectory {\tt scalar\_output}.
The minimum and maximum of {\tt grid::r} is printed according to the list
of default reductions for scalar output (parameter {\tt
IOBasic::outScalar\_reductions}). This list is overridden for {\tt
wavetoy::phi} where only the L1 norm
is output as specified in the option string for this variable. You can also
add other reduction operators within the $\{\}$ braces.
\begin{verbatim}
IOBasic::outScalar_every = 10
IOBasic::outScalar_vars = "grid::coordinates grid::coarse_dx wavetoy::phi{'norm1'}"
IOBasic::outScalar_reductions = "minimum maximum"
IOBasic::outScalar_style = "gnuplot"
IOBasic::out_dir = "scalar_output"
\end{verbatim}
This would create the following ASCII files:
\begin{verbatim}
~/Cactus/par> ls scalar_output
coarse_dx.asc r_minimum.asc x_minimum.asc y_minimum.asc z_minimum.asc
r_maximum.asc x_maximum.asc y_maximum.asc z_maximum.asc phi_norm1.asc
\end{verbatim}
%
%
\section{Comments}
%
{\bf Possible Reduction Operations}\\
%
In order to get output of reduction values for {\tt CCTK\_GF} and {\tt
CCTK\_ARRAY} variables you need to activate a thorn which provides
reduction operators (eg. thorn {\tt PUGHReduce} in the {\tt CactusPUGH}
arrangement). For a list of possible reduction operations please refer to
the documention of this reduction thorn.\\[3ex]
%
{\bf Getting Output from {\bf IOBasic}'s I/O Mehtods}\\
%
You obtain output by an I/O method by either
%
\begin{itemize}
\item setting the appropriate I/O parameters
\item calling one of the routines of the I/O function interface
provided by the flesh
\end{itemize}
%
For a description of basic I/O parameters and the I/O function interface to
invoke I/O methods by application thorns please see the documentation of thorn
{\tt IOUtil} and the flesh.\\[3ex]
%
%
{\bf Building Cactus configurations with {\bf IOBasic}}\\
%
Since {\bf IOBasic} uses parameters from {\tt IOUtil} it also needs this I/O
helper thorn be compiled into Cactus and activated at runtime in the
{\tt ActiveThorns} parameter in your parameter file.
% Do not delete next line
% END CACTUS THORNGUIDE
\end{document}
|
