xx IOBasic

IOBasic

Gabrielle Allen Thomas Radke

Date

Abstract

Thorn IOBasic provides I/O methods for outputting scalar values in ASCII format into files 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 flesh which both output the same following information:

for CCTKxSCALAR variables, the value of the scalar versus time for CCTKxGF and CCTKxARRAY variables, the values of global reduction operations (eg. minimum, maximum, L1, and L2 norm) versus time

The I/O methods differ in the destination the output is written to:

Scalar

This method outputs the information into ASCII files named "<scalarxname>.{asc|xg}" (for CCTKxSCALAR variables) and "<varxname>x<reduction>.{asc|xg}" (for CCTKxGF and CCTKxARRAY 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" files) or gnuplot (for "*.asc" files). 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::outScalarxcriterion (steerable)

The criterion that decides when to Scalar output. If this parameter is set in the parameter file, it will override the setting of the shared IO::outxcriterion parameter.

IOBasic::outScalarxevery (steerable)

How often, in terms of iterations, to do Scalar output. If this parameter is set in the parameter file, it will override the setting of the shared IO::outxevery parameter.

IOBasic::outScalarxdt (steerable)

How often, in terms of simulation time, to do Scalar output. If this parameter is set in the parameter file, it will override the setting of the shared IO::outxdt parameter.

IOBasic::outxdir

The directory in which to place the 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 Scalar output will go to the standard output directory as

specified in IO::outxdir.

IOBasic::outScalarxstyle

How to start comments in the Scalar ASCII output files. Possible choices for this keywork parameter are xgraph and gnuplot.

IOBasic::outxformat (steerable)

The output format for floating-point numbers in Scalar output. This parameter conforms to the format modifier of the C library routine fprintf(3). You can set the format for outputting floating-point numbers (fixed or exponential) as well as their precision (number of digits).

IOBasic::outScalarxvars (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 all requests Scalar output for all variables. Multiple variables must be separated by spaces. For CCTKxGF and CCTKxARRAY 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::outScalarxreductions (steerable)

The list of global reduction operations to perform on CCTKxGF and CCTKxARRAY 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::outInfoxcriterion (steerable)

The criterion that decides when to Info output. If this parameter is set in the parameter file, it will override the setting of the shared IO::outxcriterion parameter.

IOBasic::outInfoxevery (steerable)

How often, in terms of iterations, to do Info output. If this parameter is set in the parameter file, it will override the setting of the shared IO::outxevery parameter.

IOBasic::outInfoxdt (steerable)

How often, in terms of simulation time, to do Info output. If this parameter is set in the parameter file, it will override the setting of the shared IO::outxdt parameter.

IOBasic::outInfoxvars (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 all requests Info output for all variables. Multiple variables must be separated by spaces. For CCTKxGF and CCTKxARRAY 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::outInfoxreductions (steerable)

The default list of global reduction operations to perform on CCTKxGF and CCTKxARRAY 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::outInfoxreductions). This list is overridden for 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 mythorn::complex both the real and imaginary part are printed.

xxIOBasic::outInfo_everyxxxxxx=x2
xxIOBasic::outInfo_varsxxxxxxx=x"grid::r
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxwavetoy::phi{reductionsx=x'norm2'}
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxmythorn::complex"
xxIOBasic::outInfo_reductionsx=x"minimumxmaximum"

The resulting screen output would look like this:

---------------------------------------------------------------------------------------------
xxitxx|xxxxxxxxxx|xGRID::rxxxxxxxxxxxxxxxxxxxxx|xWAVETOY::phix|xMYTHORN::complexxxxxxxxxxxxx|
xxxxxx|xxxxtxxxxx|xminimumxxxxxx|xmaximumxxxxxx|xnorm2xxxxxxxx|xrealxpartxxxx|ximagxpartxxxx|
---------------------------------------------------------------------------------------------
xxxx0x|xxxx0.000x|xxx0.02986294x|xxx0.86602540x|xxx0.04217014x|xxx6.90359593x|xxx0.00000000x|
xxxx2x|xxxx0.034x|xxx0.02986294x|xxx0.86602540x|xxx0.00934749x|xxx6.90359593x|xxx0.00000000x|
xxxx4x|xxxx0.069x|xxx0.02986294x|xxx0.86602540x|xxx0.02989811x|xxx6.90359593x|xxx0.00000000x|
xxxx6x|xxxx0.103x|xxx0.02986294x|xxx0.86602540x|xxx0.05899959x|xxx6.90359593x|xxx0.00000000x|
xxxx8x|xxxx0.138x|xxx0.02986294x|xxx0.86602540x|xxx0.07351147x|xxx6.90359593x|xxx0.00000000x|
xxx10x|xxxx0.172x|xxx0.02986294x|xxx0.86602540x|xxx0.07781795x|xxx6.90359593x|xxx0.00000000x|

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::coarsexdx.

Output occurs every 10th iteration. gnuplot output style is selected for the ASCII files which are placed into a subdirectory scalarxoutput. The minimum and maximum of grid::r is printed according to the list of default reductions for scalar output (parameter IOBasic::outScalarxreductions). This list is overridden for 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.

xxIOBasic::outScalar_everyxxxxxx=x10
xxIOBasic::outScalar_varsxxxxxxx=x"grid::coordinatesxgrid::coarse_dxxwavetoy::phi{reductionsx=x'norm1'}"
xxIOBasic::outScalar_reductionsx=x"minimumxmaximum"
xxIOBasic::outScalar_stylexxxxxx=x"gnuplot"
xxIOBasic::out_dirxxxxxxxxxxxxxx=x"scalar_output"

This would create the following ASCII files:

xx~/Cactus/par>xlsxscalar_output
xxcoarse_dx.ascxxr_minimum.ascxxx_minimum.ascxxy_minimum.ascxxz_minimum.asc
xxr_maximum.ascxxx_maximum.ascxxy_maximum.ascxxz_maximum.ascxxphi_norm1.asc

4 Comments

Possible Reduction Operations In order to get output of reduction values for CCTKxGF and CCTKxARRAY 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 flesh

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

Building Cactus configurations 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 file.

5 Parameters

11outxdir 10Scope: privatex01 STRING

11Description: Output directory for IOBasic’s scalar files, overrides IO::outxdir

11 Range 10 x01 Default: (none)
11.+  10A valid directory name
11ˆ$  10An empty string to choose the default from IO::outxdir

11

11outxformat  10Scope: privatex01  STRING

11Description: Which format for Scalar floating-point number output

11 Range 10 x01 Default: .13f
11see [1] below  10output with given precision in exponential / floating point notation

11

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

11outinfoxcriterion  10Scope: privatex01  KEYWORD

11Description: Criterion to select Info output intervals

11 Range 10 x01 Default: iteration
11never  10Never output
11iteration  10Output every so many iterations
11time  10Output every that much coordinate time

11

11outinfoxdt  10Scope: privatex01  REAL

11Description: How often to do Info output

11 Range 10 x01 Default: -2
11(0:*  10In intervals of that much coordinate time
11                   10As often as possible
11-1  10Disable output
11-2  10Default to IO::outxdt

11

11outinfoxevery  10Scope: privatex01  INT

11Description: How often to do Info output

11 Range 10 x01 Default: -1
111:*  10Every so many iterations
110:  10Disable Info output
11-1:  10Default to IO::outxevery

11

11outinfoxreductions 10Scope: privatex01  STRING

11Description: List of reductions to output as Info to screen

11 Range 10 x01 Default: minimum maximum
11.+  10Space-separated list of reduction operators

11

11outinfoxvars  10Scope: privatex01  STRING

11Description: Variables to output as Info to screen

11 Range 10 x01 Default: (none)
11.+  10Space-separated list of fully qualified variable/group names
11ˆ$  10An empty string to output nothing

11

11outscalarxcriterion 10Scope: privatex01  KEYWORD

11Description: Criterion to select Scalar output intervals

11 Range 10 x01 Default: iteration
11never  10Never output
11iteration  10Output every so many iterations
11time  10Output every that much coordinate time

11

11outscalarxdt  10Scope: privatex01  REAL

11Description: How often to do Scalar output

11 Range 10 x01 Default: -2
11(0:*  10In intervals of that much coordinate time
11                   10As often as possible
11-1  10Disable output
11-2  10Default to IO::outxdt

11outscalarxevery  10Scope: privatex01  INT

11Description: How often to do Scalar output

11 Range 10 x01 Default: -1
111:*  10Every so many iterations
110:  10Disable Scalar output
11-1:  10Default to IO::outxevery

11

11outscalarxreductions 10Scope: privatex01  STRING

11Description: List of reductions to output into files

11 Range 10 x01 Default: minimum maximum norm1 norm2
11.+  10Space-separated list of reduction operators

11

11outscalarxstyle  10Scope: privatex01  KEYWORD

11Description: Which style for Scalar output

11 Range 10 x01 Default: xgraph
11gnuplot  101D output readable by gnuplot
11xgraph  101D output readable by xgraph

11

11outscalarxvars  10Scope: privatex01  STRING

11Description: Variables to output into files

11 Range 10 x01 Default: (none)
11.+  10Space-separated list of fully qualified variable/group names
11ˆ$  10An empty string to output nothing

11

11ioxoutxdir  10Scope: shared from IOx01STRING

11

11newxfilenamexscheme 10Scope: shared from IOx01BOOLEAN

11

11outxcriterion  10Scope: shared from IOx01KEYWORD

11

11outxdt  10Scope: shared from IOx01REAL

11

11outxevery  10Scope: shared from IOx01INT

11

11outxfileinfo  10Scope: shared from IOx01KEYWORD

11

11strictxioxparameterxcheck 10Scope: shared from IOx01BOOLEAN

11

11verbose  10Scope: shared from IOx01KEYWORD

6 Interfaces

General Implements: iobasic

Inherits: io

Grid Variables

6.0.1 PRIVATE GROUPS

11 x Group Names x 10 x Variable Names x x01 Details x11x
11 nextxinfoxoutputxtime 10 nextxinfoxoutputxtime x01  compact110
11                     10  x01 dimensions110
11                     10  x01 distribution11CONSTANT
11                     10  x01 group type11SCALAR
11                     10  x01 timelevels111
11                     10  x01variable type11REAL
11nextxscalarxoutputxtime10nextxscalarxoutputxtimex01  compact110
11                     10  x01 dimensions110
11                     10  x01 distribution11CONSTANT
11                     10  x01 group type11SCALAR
11                     10  x01 timelevels111
11                     10  x01variable type11REAL

11

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 x

11Always:  11x
11nextxinfoxoutputxtime nextxscalarxoutputxtime11x

11x  11x

11

Scheduled Functions

CCTKxSTARTUP x iobasicxstartup x startup routine x

11x11After: 11ioutilxstartup
11 x 11Language:11c
11 x 11Type: 11function

11

CCTKxINITIAL x iobasicxinit x initialisation routine x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11iobasic::nextxinfoxoutputxtime(everywhere)
11 x 11x  11iobasic::nextxscalarxoutputxtime(everywhere)