## IOBasic

Date

Abstract

Thorn IOBasic provides I/O methods for outputting scalar values in ASCII format into ﬁles and for printing them as runtime information to screen.

### 1 Purpose

Thorn IOBasic registers 2 I/O methods with the I/O interface in the ﬂesh which both output the same following information:

• for CCTK_SCALAR variables, the value of the scalar versus time
• for CCTK_GF and CCTK_ARRAY variables, the values of global reduction operations (eg. minimum, maximum, L1, and L2 norm) versus time

The I/O methods diﬀer in the destination the output is written to:

• Scalar
This method outputs the information into ASCII ﬁles named "<scalar_name>.{asc|xg}" (for CCTK_SCALAR variables) and "<var_name>_<reduction>.{asc|xg}" (for CCTK_GF and CCTK_ARRAY variables where reduction would stand for the type of reduction value that is output).
The output data can be plotted by using either xgraph (for "*.xg" ﬁles) or gnuplot (for "*.asc" ﬁles). The output style can be selected via parameter settings.
• Info
This method prints the data as runtime information to 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.

### 2 IOBasic Parameters

Parameters to control the Scalar I/O method are:

• IOBasic::outScalar_criterion (steerable)
The criterion that decides when to Scalar output. If this parameter is set in the parameter ﬁle, it will override the setting of the shared IO::out_criterion parameter.
• IOBasic::outScalar_every (steerable)
How often, in terms of iterations, to do Scalar output. If this parameter is set in the parameter ﬁle, it will override the setting of the shared IO::out_every parameter.
• IOBasic::outScalar_dt (steerable)
How often, in terms of simulation time, to do Scalar output. If this parameter is set in the parameter ﬁle, it will override the setting of the shared IO::out_dt parameter.
• IOBasic::out_dir
The directory in which to place the Scalar ASCII output ﬁles. If the directory doesn’t exist at startup it will be created.
If this paraeter is set to an empty string Scalar output will go to the standard output directory as speciﬁed in IO::out_dir.
• IOBasic::outScalar_style
How to start comments in the Scalar ASCII output ﬁles.
Possible choices for this keywork parameter are xgraph and gnuplot.
• IOBasic::out_format (steerable)
The output format for ﬂoating-point numbers in Scalar output.
This parameter conforms to the format modiﬁer of the C library routine fprintf(3). You can set the format for outputting ﬂoating-point numbers (ﬁxed or exponential) as well as their precision (number of digits).
• IOBasic::outScalar_vars (steerable)
The list of variables to output into individual ASCII ﬁles.
The variables must be given by their fully qualiﬁed variable or group name. The special keyword all requests 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.
• IOBasic::outScalar_reductions (steerable)
The list of global reduction operations to perform on CCTK_GF and CCTK_ARRAY variables for Scalar output. This setting can be overridden for individual variables using an option string.
Multiple reduction names must be separated by spaces.

Parameters to control the Info I/O method are:

• IOBasic::outInfo_criterion (steerable)
The criterion that decides when to Info output. If this parameter is set in the parameter ﬁle, it will override the setting of the shared IO::out_criterion parameter.
• IOBasic::outInfo_every (steerable)
How often, in terms of iterations, to do Info output. If this parameter is set in the parameter ﬁle, it will override the setting of the shared IO::out_every parameter.
• IOBasic::outInfo_dt (steerable)
How often, in terms of simulation time, to do Info output. If this parameter is set in the parameter ﬁle, it will override the setting of the shared IO::out_dt parameter.
• IOBasic::outInfo_vars (steerable)
The list of variables to output to screen.
The variables must be given by their fully qualiﬁed variable or group name. The special keyword all requests 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.
• 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.

All of the above parameters marked as steerable can be changed at runtime.

### 3 Examples

#### 3.1 Example for Info Output

The following parameter settings request info output for variables grid::r, wavetoy::phi (both are CCTK grid functions) and mythorn::complex (a complex CCTK scalar) at every other iteration.

The minimum and maximum of grid::r is printed according to the list of default reductions for info output (parameter IOBasic::outInfo_reductions). This list is overridden for wavetoy::phi where only the L2 norm is output as speciﬁed in the option string for this variable. You can also add other reduction operators within the $\left\{\right\}$ braces.

For the scalar variable mythorn::complex both the real and imaginary part are printed.

IOBasic::outInfo_every      = 2
IOBasic::outInfo_vars       = "grid::r
wavetoy::phi{reductions = ’norm2’}
mythorn::complex"
IOBasic::outInfo_reductions = "minimum maximum"

The resulting screen output would look like this:

---------------------------------------------------------------------------------------------
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 |

#### 3.2 Example for Scalar Output

The following parameter settings request scalar output for all grid function variables in the group grid::coordinates and for the scalar variable grid::coarse_dx.
Output occurs every 10th iteration. gnuplot output style is selected for the ASCII ﬁles which are placed into a subdirectory scalar_output. The minimum and maximum of grid::r is printed according to the list of default reductions for scalar output (parameter IOBasic::outScalar_reductions). This list is overridden for wavetoy::phi where only the L1 norm is output as speciﬁed in the option string for this variable. You can also add other reduction operators within the $\left\{\right\}$ braces.

IOBasic::outScalar_every      = 10
IOBasic::outScalar_vars       = "grid::coordinates grid::coarse_dx wavetoy::phi{reductions = ’norm1’}"
IOBasic::outScalar_reductions = "minimum maximum"
IOBasic::outScalar_style      = "gnuplot"
IOBasic::out_dir              = "scalar_output"

This would create the following ASCII ﬁles:

~/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

Possible Reduction Operations
In order to get output of reduction values for CCTK_GF and CCTK_ARRAY variables you need to activate a thorn which provides reduction operators (eg. thorn PUGHReduce in the CactusPUGH arrangement). For a list of possible reduction operations please refer to the documention of this reduction thorn.
Getting Output from IOBasic’s I/O Mehtods
You obtain output by an I/O method by either

• setting the appropriate I/O parameters
• calling one of the routines of the I/O function interface provided by the ﬂesh

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 IOUtil and the ﬂesh.
Building Cactus conﬁgurations with IOBasic
Since IOBasic uses parameters from IOUtil it also needs this I/O helper thorn be compiled into Cactus and activated at runtime in the ActiveThorns parameter in your parameter ﬁle.

### 5 Parameters

 out_dir Scope: private STRING Description: Output directory for IOBasic’s scalar ﬁles, overrides IO::out_dir Range Default: (none) .+ A valid directory name \$̂ An empty string to choose the default from IO::out_dir

 out_format Scope: private STRING Description: Which format for Scalar ﬂoating-point number output Range Default: .13f see [1] below output with given precision in exponential / ﬂoating point notation

[1]

\^({\textbackslash}.[1]?[0-9])?[EGefg]\\$

 outinfo_criterion Scope: private KEYWORD Description: Criterion to select Info output intervals Range Default: iteration never Never output iteration Output every so many iterations time Output every that much coordinate time

 outinfo_dt Scope: private REAL Description: How often to do Info output Range Default: -2 (0:* In intervals of that much coordinate time As often as possible -1 Disable output -2 Default to IO::out_dt

 outinfo_every Scope: private INT Description: How often to do Info output Range Default: -1 1:* Every so many iterations 0: Disable Info output -1: Default to IO::out_every

 outinfo_reductions Scope: private STRING Description: List of reductions to output as Info to screen Range Default: minimum maximum .+ Space-separated list of reduction operators

 outinfo_vars Scope: private STRING Description: Variables to output as Info to screen Range Default: (none) .+ Space-separated list of fully qualiﬁed variable/group names \$̂ An empty string to output nothing

 outscalar_criterion Scope: private KEYWORD Description: Criterion to select Scalar output intervals Range Default: iteration never Never output iteration Output every so many iterations time Output every that much coordinate time

 outscalar_dt Scope: private REAL Description: How often to do Scalar output Range Default: -2 (0:* In intervals of that much coordinate time As often as possible -1 Disable output -2 Default to IO::out_dt

 outscalar_every Scope: private INT Description: How often to do Scalar output Range Default: -1 1:* Every so many iterations 0: Disable Scalar output -1: Default to IO::out_every

 outscalar_reductions Scope: private STRING Description: List of reductions to output into ﬁles Range Default: minimum maximum norm1 norm2 .+ Space-separated list of reduction operators

 outscalar_style Scope: private KEYWORD Description: Which style for Scalar output Range Default: xgraph gnuplot 1D output readable by gnuplot xgraph 1D output readable by xgraph

 outscalar_vars Scope: private STRING Description: Variables to output into ﬁles Range Default: (none) .+ Space-separated list of fully qualiﬁed variable/group names \$̂ An empty string to output nothing

 io_out_dir Scope: shared from IO STRING

 new_ﬁlename_scheme Scope: shared from IO BOOLEAN

 out_criterion Scope: shared from IO KEYWORD

 out_dt Scope: shared from IO REAL

 out_every Scope: shared from IO INT

 out_ﬁleinfo Scope: shared from IO KEYWORD

 strict_io_parameter_check Scope: shared from IO BOOLEAN

 verbose Scope: shared from IO KEYWORD

### 6 Interfaces

Implements:

iobasic

Inherits:

io

#### Grid Variables

##### 6.0.1 PRIVATE GROUPS
 Group Names Variable Names Details next_info_output_time compact 0 next_info_output_time dimensions 0 distribution CONSTANT group type SCALAR timelevels 1 variable type REAL next_scalar_output_time compact 0 next_scalar_output_time dimensions 0 distribution CONSTANT group type SCALAR timelevels 1 variable type REAL

### 7 Schedule

This section lists all the variables which are assigned storage by thorn CactusBase/IOBasic. Storage can either last for the duration of the run (Always means that if this thorn is activated storage will be assigned, Conditional means that if this thorn is activated storage will be assigned for the duration of the run if some condition is met), or can be turned on for the duration of a schedule function.

#### Storage

 Always: next_info_output_time next_scalar_output_time

#### Scheduled Functions

CCTK_STARTUP

iobasic_startup

startup routine

 After: ioutil_startup Language: c Type: function

CCTK_INITIAL

iobasic_init

initialisation routine

 Language: c Type: function