Thorn IOASCII provides I/O methods for 1D, 2D, and 3D output of grid arrays and grid functions into files in ASCII format. The precise format is designed for visualisation using the clients xgraph [1] or gnuplot [2].
Thorn IOASCII registers three I/O methods named IOASCII_1D, IOASCII_2D, and IOASCII_3D with the I/O interface in the flesh.
IOASCII_1D
creates one-dimensional output of 1D, 2D and 3D grid functions and arrays by slicing through the edge (in
the octant case) or center (in all origin centered cases) of the grid in the coordinate directions. In addition,
output is provided along a diagonal of the grid, in this case the diagonal always starts at the
first grid point (that is, in Fortran notation var(1,1,1)) and the line taken uses grid points
increasing by 1 in each direction. [NOTE: The diagonal output is not available for staggered
variables].
Output for each direction can be selected individually via parameters.
Data is written in ASCII format and goes into files with the names:
<variable_name>_<slice>_[<center_i>][<center_j>].{asc|xg}
and for diagonals:
<variable_name>_3D_diagonal.{asc|xg}
These files can be processed directly by either xgraph or gnuplot (you can select the style of output via parameter settings).
IOASCII_2D outputs two-dimensional slices of grid functions and arrays planes. Again, slicing is done
through the edge (in the octant case) or center (in all origin centered cases).
Data is written in ASCII format and goes into files named
<variable_name>_<plane>_[<center>].{asc|xg}
These files can be visualized by gnuplot using its splot command.
IOASCII_3D outputs three-dimensional grid functions and arrays as a whole.
Data is written in ASCII format and goes into files named
<variable_name>_3D.{asc|xg}
These files can be visualized by gnuplot using its splot command.
General parameters to control all IOASCII’s I/O methods are:
IOASCII::out[123]D_every (steerable)
How often to do periodic IOASCII output. If this parameter is set in the parameter file, it will
override the setting of the shared IO::out_every parameter. The output frequency can also be
set for individual variables using the out_every option in an option string appended to the
IOASCII::out[123]D_vars parameter.
IOASCII::out[123]D_vars (steerable)
The list of variables to output using an IOASCII I/O method. The variables must be given by
their fully qualified variable or group name. The special keyword all requests IOASCII output for
all variables. Multiple names must be separated by whitespaces.
An option string can be appended in curly braces to the group/variable name. The only option
supported so far is out_every which sets the output frequency for an individual variable (overriding
IOASCII::out[123]D_every and IO::out_every).
IOASCII::out[123]D_dir
The directory in which to place the IOASCII output files. If the directory doesn’t exist at startup
it will be created.
If this parameter is set to an empty string IOASCII output will go to the standard output directory
as specified in IO::out_dir.
IOASCII::out_format (steerable)
The output format for floating-point numbers in IOASCII 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).
IOASCII::out[123]D_style
The output style for IOASCII output.
This parameter chooses between gnuplot- and xgraph-suitable output style, and – for gnuplot –
determines whether to also plot the physical time in the output data or not.
Additional parameters to control the IOASCII_1D I/O method are:
IOASCII::out1D_[xyzd] (steerable)
Chooses the directions to output in 1D IOASCII format (d stands for diagonal direction).
IOASCII::out1D_[xyz]line_[xyz], IOASCII::out1D_[xyz]line_[xyz]i
Chooses the slice centers for 1D lines from IOASCII_1D. These can be set either in physical or
index coordinates. If they are set these parameters will override the default slice center parameters
IO::out_[xyz]line[xyz], IO::out_[xyz]line[xyz]i. Note that the slice center can only be set
for grid functions so far. For CCTK_ARRAY variables the slices will always start in the origin, ie. (0,
0, 0) in C ordering.
Additional parameters to control the IOASCII_2D I/O method are:
IOASCII::out2D_[xyxzyz]plane_[xyz], IOASCII::out2D_[xyxzyz]plane_[xyz]i
Chooses the slice centers for 2D planes from IOASCII_2D. These can be set either in physical or
index coordinates. If they are set these parameters will override the default slice center parameters
IO::out_[xyxzyz]plane[xyz], IO::out_[xyxzyz]plane[xyz]i.
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 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 IOASCII 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.
In this section we include example output for different parameter combinations. Note that all these examples were generated for just a couple of timesteps for an extremely small 3D grid.
These options produce data suitable for using with the xgraph visualization client in the format
x f(t=fixed,x,y=fixed,z=fixed):
IOASCII::out1D_every = 1 IOASCII::out1D_vars = "wavetoy::phi" IOASCII::out1D_style = "xgraph"
Output File: phi_x_[1][1].xg
"Parameter file wavetoy.par "Created Sun 19 Aug 2001 16:31:43 "x-label x "y-label WAVETOY::phi (y = 0.0000000000000, z = 0.0000000000000), (yi = 1, zi = 1) "Time = 0.0000000000000 -0.5000000000000 0.0000000000139 0.0000000000000 1.0000000000000 0.5000000000000 0.0000000000139 "Time = 0.2500000000000 -0.5000000000000 0.0000000000000 0.0000000000000 0.4980695458846 0.5000000000000 0.0000000000000 "Time = 0.5000000000000 -0.5000000000000 0.0019304541362 0.0000000000000 -0.7509652270577 0.5000000000000 0.0019304541362
These options produce data suitable for using with the gnuplot visualization client in the format
x f(t,x,y=fixed,z=fixed):
IOASCII::out1D_every = 1 IOASCII::out1D_vars = "wavetoy::phi" IOASCII::out1D_style = "gnuplot f(x)"
Output File: phi_x_[1][1].asc
#Parameter file wavetoy.par #Created Sun 19 Aug 2001 16:33:07 #x-label x #y-label WAVETOY::phi (y = 0.0000000000000, z = 0.0000000000000), (yi = 1, zi = 1) #Time = 0.0000000000000 -0.5000000000000 0.0000000000139 0.0000000000000 1.0000000000000 0.5000000000000 0.0000000000139 #Time = 0.2500000000000 -0.5000000000000 0.0000000000000 0.0000000000000 0.4980695458846 0.5000000000000 0.0000000000000 #Time = 0.5000000000000 -0.5000000000000 0.0019304541362 0.0000000000000 -0.7509652270577 0.5000000000000 0.0019304541362
These options produce data suitable for using with the gnuplot visualization client in the format
t x f(t,x,y=fixed,z=fixed):
IOASCII::out1D_every = 1 IOASCII::out1D_vars = "wavetoy::phi" IOASCII::out1D_style = "gnuplot f(t,x)"
Output file: phi_x_[1][1].asc
#Parameter file wavetoy.par #Created Sun 19 Aug 2001 16:34:48 #x-label x #y-label WAVETOY::phi (y = 0.0000000000000, z = 0.0000000000000), (yi = 1, zi = 1) #Time = 0.0000000000000 0.0000000000000 -0.5000000000000 0.0000000000139 0.0000000000000 0.0000000000000 1.0000000000000 0.0000000000000 0.5000000000000 0.0000000000139 #Time = 0.2500000000000 0.2500000000000 -0.5000000000000 0.0000000000000 0.2500000000000 0.0000000000000 0.4980695458846 0.2500000000000 0.5000000000000 0.0000000000000 #Time = 0.5000000000000 0.5000000000000 -0.5000000000000 0.0019304541362 0.5000000000000 0.0000000000000 -0.7509652270577 0.5000000000000 0.5000000000000 0.0019304541362
These options produce data suitable for using with the gnuplot visualization client in the format
x y f(t,x,y,z=fixed):
IOASCII::out2D_every = 1 IOASCII::out2D_vars = "wavetoy::phi" IOASCII::out2D_style = "gnuplot f(x,y)"
Output file: phi_xy_[1].asc
#Parameter file wavetoy.par
#Created Sun 19 Aug 2001 16:31:43
#x-label x
#y-label y
#z-label WAVETOY::phi (z = 0.0000000000000), (zi = 1)
#Time = 0.0000000000000
-0.5000000000000 -0.5000000000000 0.0000000000000
0.0000000000000 -0.5000000000000 0.0000000000139
0.5000000000000 -0.5000000000000 0.0000000000000
-0.5000000000000 0.0000000000000 0.0000000000139
0.0000000000000 0.0000000000000 1.0000000000000
0.5000000000000 0.0000000000000 0.0000000000139
-0.5000000000000 0.5000000000000 0.0000000000000
0.0000000000000 0.5000000000000 0.0000000000139
0.5000000000000 0.5000000000000 0.0000000000000
#Time = 0.2500000000000
-0.5000000000000 -0.5000000000000 0.0000000000000
0.0000000000000 -0.5000000000000 0.0000000000000
0.5000000000000 -0.5000000000000 0.0000000000000
-0.5000000000000 0.0000000000000 0.0000000000000
0.0000000000000 0.0000000000000 0.4980695458846
0.5000000000000 0.0000000000000 0.0000000000000
-0.5000000000000 0.5000000000000 0.0000000000000
0.0000000000000 0.5000000000000 0.0000000000000
0.5000000000000 0.5000000000000 0.0000000000000
#Time = 0.5000000000000
-0.5000000000000 -0.5000000000000 0.0000000008425
0.0000000000000 -0.5000000000000 0.0019304541362
0.5000000000000 -0.5000000000000 0.0000000008425
-0.5000000000000 0.0000000000000 0.0019304541362
0.0000000000000 0.0000000000000 -0.7509652270577
0.5000000000000 0.0000000000000 0.0019304541362
-0.5000000000000 0.5000000000000 0.0000000008425
0.0000000000000 0.5000000000000 0.0019304541362
0.5000000000000 0.5000000000000 0.0000000008425
These options produce data suitable for using with the gnuplot visualization client in the format
t x y f(t,x,y,z=fixed):
IOASCII::out2D_every = 1 IOASCII::out2D_vars = "wavetoy::phi" IOASCII::out2D_style = "gnuplot f(t,x,y)"
Output file: phi_xy_[1].asc
#Parameter file wavetoy.par
#Created Sun 19 Aug 2001 16:33:07
#x-label x
#y-label y
#z-label WAVETOY::phi (z = 0.0000000000000), (zi = 1)
#Time = 0.0000000000000
0.0000000000000 -0.5000000000000 -0.5000000000000 0.0000000000000
0.0000000000000 0.0000000000000 -0.5000000000000 0.0000000000139
0.0000000000000 0.5000000000000 -0.5000000000000 0.0000000000000
0.0000000000000 -0.5000000000000 0.0000000000000 0.0000000000139
0.0000000000000 0.0000000000000 0.0000000000000 1.0000000000000
0.0000000000000 0.5000000000000 0.0000000000000 0.0000000000139
0.0000000000000 -0.5000000000000 0.5000000000000 0.0000000000000
0.0000000000000 0.0000000000000 0.5000000000000 0.0000000000139
0.0000000000000 0.5000000000000 0.5000000000000 0.0000000000000
#Time = 0.2500000000000
0.2500000000000 -0.5000000000000 -0.5000000000000 0.0000000000000
0.2500000000000 0.0000000000000 -0.5000000000000 0.0000000000000
0.2500000000000 0.5000000000000 -0.5000000000000 0.0000000000000
0.2500000000000 -0.5000000000000 0.0000000000000 0.0000000000000
0.2500000000000 0.0000000000000 0.0000000000000 0.4980695458846
0.2500000000000 0.5000000000000 0.0000000000000 0.0000000000000
0.2500000000000 -0.5000000000000 0.5000000000000 0.0000000000000
0.2500000000000 0.0000000000000 0.5000000000000 0.0000000000000
0.2500000000000 0.5000000000000 0.5000000000000 0.0000000000000
#Time = 0.5000000000000
0.5000000000000 -0.5000000000000 -0.5000000000000 0.0000000008425
0.5000000000000 0.0000000000000 -0.5000000000000 0.0019304541362
0.5000000000000 0.5000000000000 -0.5000000000000 0.0000000008425
0.5000000000000 -0.5000000000000 0.0000000000000 0.0019304541362
0.5000000000000 0.0000000000000 0.0000000000000 -0.7509652270577
0.5000000000000 0.5000000000000 0.0000000000000 0.0019304541362
0.5000000000000 -0.5000000000000 0.5000000000000 0.0000000008425
0.5000000000000 0.0000000000000 0.5000000000000 0.0019304541362
0.5000000000000 0.5000000000000 0.5000000000000 0.0000000008425
[1] http://www.cactuscode.org/VizTools/xgraph.html, http://jean-luc.aei.mpg.de/Codes/xgraph/
[2] http://www.cactuscode.org/VizTools/Gnuplot.html, http://www.gnuplot.info
| out1d_d | Scope: private | BOOLEAN |
| Description: Do 1D IOASCII output in the diagonal-direction
| ||
| Default: yes | ||
| out1d_dir | Scope: private | STRING |
| Description: Output directory for 1D IOASCII files, overrides IO::out_dir
| ||
| Range | Default: (none) | |
| .+ | A valid directory name
| |
 | An empty string to choose the default from IO::out_dir
| |
| out1d_every | Scope: private | INT |
| Description: How often to do 1D IOASCII output, overrides IO::out_every
| ||
| Range | Default: -1 | |
| 1:* | Every so many iterations
| |
| 0: | Disable 1D IOASCII output
| |
| -1: | Default to IO::out_every
| |
| out1d_style | Scope: private | KEYWORD |
| Description: Which style for 1D lines IOASCII output
| ||
| Range | Default: xgraph | |
| xgraph | f over x plots suitable for xgraph
| |
| gnuplot f(x) | f over x plots suitable for gnuplot
| |
| gnuplot f(t,x) | f over t,x plots suitable for gnuplot
| |
| out1d_vars | Scope: private | STRING |
| Description: Variables to output in 1D IOASCII file format
| ||
| Range | Default: (none) | |
| .+ | Space-separated list of fully qualified variable/group names
| |
 | An empty string to output nothing
| |
| out1d_x | Scope: private | BOOLEAN |
| Description: Do 1D IOASCII output in the x-direction
| ||
| Default: yes | ||
| out1d_xline_y | Scope: private | REAL |
| Description: y-coord for 1D lines in x-direction
| ||
| Range | Default: -424242 | |
| *:* | A value between [ymin, ymax]
| |
| -424242: | Default to IO::out_xline_y
| |
| out1d_xline_yi | Scope: private | INT |
| Description: y-index (from 0) for 1D lines in x-direction
| ||
| Range | Default: -1 | |
| 0:* | An index between [0, ny)
| |
| -1: | Choose the default from IO::out_xline_yi
| |
| out1d_xline_z | Scope: private | REAL |
| Description: z-coord for 1D lines in x-direction
| ||
| Range | Default: -424242 | |
| *:* | A value between [zmin, zmax]
| |
| -424242: | Default to IO::out_xline_z
| |
| out1d_xline_zi | Scope: private | INT |
| Description: z-index (from 0) for 1D lines in x-direction
| ||
| Range | Default: -1 | |
| 0:* | An index between [0, nz)
| |
| -1: | Choose the default from IO::out_xline_zi
| |
| out1d_y | Scope: private | BOOLEAN |
| Description: Do 1D IOASCII output in the y-direction
| ||
| Default: yes | ||
| out1d_yline_x | Scope: private | REAL |
| Description: x-coord for 1D lines in y-direction
| ||
| Range | Default: -424242 | |
| *:* | A value between [xmin, xmax]
| |
| -424242: | Default to IO::out_yline_x
| |
| out1d_yline_xi | Scope: private | INT |
| Description: x-index (from 0) for 1D lines in y-direction
| ||
| Range | Default: -1 | |
| 0:* | An index between [0, nx)
| |
| -1: | Choose the default from IO::out_yline_xi
| |
| out1d_yline_z | Scope: private | REAL |
| Description: z-coord for 1D lines in y-direction
| ||
| Range | Default: -424242 | |
| *:* | A value between [zmin, zmax]
| |
| -424242: | Default to IO::out_yline_z
| |
| out1d_yline_zi | Scope: private | INT |
| Description: z-index (from 0) for 1D lines in y-direction
| ||
| Range | Default: -1 | |
| 0:* | An index between [0, nz)
| |
| -1: | Choose the default from IO::out_yline_zi
| |
| out1d_z | Scope: private | BOOLEAN |
| Description: Do 1D IOASCII output in the z-direction
| ||
| Default: yes | ||
| out1d_zline_x | Scope: private | REAL |
| Description: x-coord for 1D lines in z-direction
| ||
| Range | Default: -424242 | |
| *:* | A value between [xmin, xmax]
| |
| -424242: | Default to IO::out_zline_x
| |
| out1d_zline_xi | Scope: private | INT |
| Description: x-index (from 0) for 1D lines in z-direction
| ||
| Range | Default: -1 | |
| 0:* | An index between [0, nx)
| |
| -1: | Choose the default from IO::out_zline_xi
| |
| out1d_zline_y | Scope: private | REAL |
| Description: y-coord for 1D lines in z-direction
| ||
| Range | Default: -424242 | |
| *:* | A value between [ymin, ymax]
| |
| -424242: | Default to IO::out_zline_y
| |
| out1d_zline_yi | Scope: private | INT |
| Description: y-index (from 0) for 1D lines in z-direction
| ||
| Range | Default: -1 | |
| 0:* | An index between [0, ny)
| |
| -1: | Choose the default from IO::out_zline_yi
| |
| out2d_dir | Scope: private | STRING |
| Description: Output directory for 2D IOASCII files, overrides out_dir
| ||
| Range | Default: (none) | |
| .+ | A valid directory name
| |
 | An empty string to choose the default from IO::out_dir
| |
| out2d_every | Scope: private | INT |
| Description: How often to do 2D IOASCII output, overrides IO::out_every
| ||
| Range | Default: -1 | |
| 1:* | Every so many iterations
| |
| 0: | Disable 2D IOASCII output
| |
| -1: | Default to IO::out_every
| |
| out2d_style | Scope: private | KEYWORD |
| Description: Which style for 2D slices IOASCII output
| ||
| Range | Default: gnuplot f(x,y) | |
| gnuplot f(x,y) | f over x,y plots suitable for gnuplot
| |
| gnuplot f(t,x,y) | f over t,x,y plots suitable for gnuplot
| |
| out2d_vars | Scope: private | STRING |
| Description: Variables to output in 2D IOASCII file format
| ||
| Range | Default: (none) | |
| .+ | Space-separated list of fully qualified variable/group names
| |
 | An empty string to output nothing
| |
| out2d_xyplane_z | Scope: private | REAL |
| Description: z-coord for 2D planes in xy
| ||
| Range | Default: -424242 | |
| *:* | A value between [zmin, zmax]
| |
| -424242: | Default to IO::out_xyplane_z
| |
| out2d_xyplane_zi | Scope: private | INT |
| Description: z-index (from 0) for 2D planes in xy
| ||
| Range | Default: -1 | |
| 0:* | An index between [0, nz)
| |
| -1: | Choose the default from IO::out_xyplane_zi
| |
| out2d_xzplane_y | Scope: private | REAL |
| Description: y-coord for 2D planes in xz
| ||
| Range | Default: -424242 | |
| *:* | A value between [ymin, ymax]
| |
| -424242: | Default to IO::out_xzplane_y
| |
| out2d_xzplane_yi | Scope: private | INT |
| Description: y-index (from 0) for 2D planes in xz
| ||
| Range | Default: -1 | |
| 0:* | An index between [0, ny)
| |
| -1: | Choose the default from IO::out_xzplane_yi
| |
| out2d_yzplane_x | Scope: private | REAL |
| Description: x-coord for 2D planes in yz
| ||
| Range | Default: -424242 | |
| *:* | A value between [xmin, xmax]
| |
| -424242: | Default to IO::out_yzplane_x
| |
| out2d_yzplane_xi | Scope: private | INT |
| Description: x-index (from 0) for 2D planes in yz
| ||
| Range | Default: -1 | |
| 0:* | An index between [0, nx)
| |
| -1: | Choose the default from IO::out_yzplane_xi
| |
| out3d_dir | Scope: private | STRING |
| Description: Output directory for 3D IOASCII files, overrides IO::out_dir
| ||
| Range | Default: (none) | |
| .+ | A valid directory name
| |
 | An empty string to choose the default from IO::out_dir
| |
| out3d_every | Scope: private | INT |
| Description: How often to do 3D IOASCII output, overrides IO::out_every
| ||
| Range | Default: -1 | |
| 1:* | Every so many iterations
| |
| 0: | Disable 3D IOASCII output
| |
| -1: | Default to IO::out_every
| |
| out3d_style | Scope: private | KEYWORD |
| Description: Which style for 3D volume IOASCII output
| ||
| Range | Default: gnuplot f(x,y,z) | |
| gnuplot f(x,y,z) | f over x,y,z plots suitable for gnuplot
| |
| gnuplot f(t,x,y,z) | f over t,x,y,z plots suitable for gnuplot
| |
| out3d_vars | Scope: private | STRING |
| Description: Variables to output in 3D IOASCII file format
| ||
| Range | Default: (none) | |
| .+ | Space-separated list of fully qualified variable/group names
| |
 | An empty string to output nothing
| |
| out_format | Scope: private | STRING |
| Description: Which format for IOASCII floating-point number output
| ||
| Range | Default: .13f | |
| see [1] below | output with given precision in exponential / floating point notation
| |
[1]
\^({\textbackslash}.[1]?[0-9])?[EGefg]\$
| new_filename_scheme | Scope: shared from IO | BOOLEAN |
| out_dir | Scope: shared from IO | STRING |
| out_downsample_x | Scope: shared from IO | INT |
| out_downsample_y | Scope: shared from IO | INT |
| out_downsample_z | Scope: shared from IO | INT |
| out_every | Scope: shared from IO | INT |
| out_fileinfo | Scope: shared from IO | KEYWORD |
| out_xline_y | Scope: shared from IO | REAL |
| out_xline_yi | Scope: shared from IO | INT |
| out_xline_z | Scope: shared from IO | REAL |
| out_xline_zi | Scope: shared from IO | INT |
| out_xyplane_z | Scope: shared from IO | REAL |
| out_xyplane_zi | Scope: shared from IO | INT |
| out_xzplane_y | Scope: shared from IO | REAL |
| out_xzplane_yi | Scope: shared from IO | INT |
| out_yline_x | Scope: shared from IO | REAL |
| out_yline_xi | Scope: shared from IO | INT |
| out_yline_z | Scope: shared from IO | REAL |
| out_yline_zi | Scope: shared from IO | INT |
| out_yzplane_x | Scope: shared from IO | REAL |
| out_yzplane_xi | Scope: shared from IO | INT |
| out_zline_x | Scope: shared from IO | REAL |
| out_zline_xi | Scope: shared from IO | INT |
| out_zline_y | Scope: shared from IO | REAL |
| out_zline_yi | Scope: shared from IO | INT |
| strict_io_parameter_check | Scope: shared from IO | BOOLEAN |
| verbose | Scope: shared from IO | KEYWORD |
Implements:
ioascii
This section lists all the variables which are assigned storage by thorn CactusBase/IOASCII. 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.
NONE
CCTK_STARTUP
ioascii_startup
startup routine
| After: | ioutil_startup | |
| Language: | c | |
| Type: | function | |
CCTK_BASEGRID
ioascii_choose1d
choose 1d output lines
| After: | spatialcoordinates | |
| Language: | c | |
| Type: | function | |
CCTK_BASEGRID
ioascii_choose2d
choose 2d output planes
| After: | spatialcoordinates | |
| Language: | c | |
| Type: | function | |