CarpetIOASCII

Erik Schnetter <schnetter@aei.mpg.de>
Thomas Radke <tradke@aei.mpg.de>

November 20, 2005

Abstract

This thorn reproduces thorn IOASCII from arrangement CactusBase but is specifically for the driver thorn Carpet.

1 Introduction

This thorn provides ASCII output of data in 1, 2 or 3 dimensions. It reproduces most of the functionality of thorn IOASCII from the standard CactusBase arrangement. Where possible the names of parameters and their use is identical. For most purposes it should be sufficient to take a parameter file written for the standard IOASCII and just change the active thorn.

However, this thorn outputs considerably more information than the standard IOASCII thorn. Information about, e.g., the refinement level and the index position of the output are also given. All the output can be visualized using gnuplot.

The CarpetIOASCII I/O methods can output any type of CCTK grid variables (grid scalars, grid functions, and grid arrays of arbitrary dimension); data is written into separate files named "<varname>.asc".

2 CarpetIOASCII Parameters

The most important parameters to control the CarpetIOASCII I/O methods are listed below. Many parameters come as a set of four individuals, one for each I/O method, controlling 0, 1, 2, or 3-dimensional ASCII output respectively.

3 Using the flesh I/O API to produce ASCII output

Periodic output of grid variables is usually specified via I/O parameters in the parameter file and then automatically triggered by the flesh scheduler at each iteration step after analysis. If output should also be triggered at a different time, one can do that from within an application thorn by invoking one of the CCTK_OutputVar*() I/O routines provided by the flesh I/O API (see chapter B8.2 “IO” in the Cactus Users Guide). In this case, the application thorn routine which calls CCTK_OutputVar*() must be scheduled in level mode.

If output for a variable is required also for intermediate timesteps this can be achieved by calling CCTK_OutputVarAs*() with a different alias name; output for the same variable is then written into different ASCII files based on the alias argument.

4 Utilities

For those that prefer other visualization packages than gnuplot there are some utilities in the src/util directory. These are

The first two, written by Scott Hawley, are C codes that require the Makefile (building using the -utils flag from the main Cactus directory currently does not work). Each output one refinement level, either to standard output or to a file.

The third script writes all refinement levels from a given file in a given direction to a number of different files given a prefix filename, where the number in the output filename is given by the refinement level. Usage: Carpet2ygraph.pl direction Inputfile Outputfile, where direction is 0, 1, 2, for x,y and z.

The fourth script is an improved version of the previous one. It reads a 1D .asc file and produces a single file containing all the data from all levels, writing points that are in more levels only once. The output filename is the original filename with the suffix .asc changed into .xg. The direction (x,y or z) of the input file is automatically detected from the filename. It recognizes and converts also scalar data, like norms and extrema. Usage: Carpet2ygraphCat.pl Inputfile.

The fifth script can be used to merge CarpetIOASCII output written before and after recovery. It reads one or more files in CarpetIOASCII format and writes their contents to STDOUT, eliminating duplicate datasets (all but the last occurance are discarded), which may be created when a run died abruptly without checkpointing at the last output itaration and is recovered from a previous checkpoint. Usage: mergeCarpetIOASCII.pl list of files.
Example 1: mergeCarpetIOASCII.pl alp.x.asc > alp.x.asc.merged.
Example 2: mergeCarpetIOASCII.pl alp.x.asc.firstCHKPT alp.x.asc.secondCHKPT > alp.x.asc.merged.
This script was written by Thomas Radke.

5 Parameters




compact_format
Scope: private  BOOLEAN



Description: Use a more compact output format with fewer columns and lines



  Default: no






one_file_per_group
Scope: private  BOOLEAN



Description: Write one file per group instead of per variable



  Default: no






out0d_criterion
Scope: private  KEYWORD



Description: Criterion to select 0D ASCII output intervals, overrides out_every



Range   Default: default
default
Use IO::out_criterion
never
Never output
iteration
Output every so many iterations
divisor
Output if iteration mod divisor == 0.
time
Output every that much coordinate time






out0d_dir
Scope: private  STRING



Description: Name of 0D ASCII output directory, overrides IO::out_dir



Range   Default: (none)
Empty: use IO::out_dir
.+
Not empty: directory name






out0d_dt
Scope: private  REAL



Description: How often to do 0D ASCII output, overrides IO::out_dt



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






out0d_every
Scope: private  INT



Description: How often to do 0D ASCII output, overrides out_every



Range   Default: -2
1:*
Output every so many time steps
-1:0
No output
-2
Use IO::out_every






out0d_point_x
Scope: private  REAL



Description: x coordinate for 0D points



Range   Default: (none)
*:*






out0d_point_xi
Scope: private  INT



Description: x-index (counting from 0) for 0D points



Range   Default: (none)
0:*






out0d_point_y
Scope: private  REAL



Description: y coordinate for 0D points



Range   Default: (none)
*:*






out0d_point_yi
Scope: private  INT



Description: y-index (counting from 0) for 0D points



Range   Default: (none)
0:*






out0d_point_z
Scope: private  REAL



Description: z coordinate for 0D points



Range   Default: (none)
*:*






out0d_point_zi
Scope: private  INT



Description: z-index (counting from 0) for 0D points



Range   Default: (none)
0:*






out0d_vars
Scope: private  STRING



Description: Variables to output in 0D ASCII file format



Range   Default: (none)
List of group or variable names






out1d_criterion
Scope: private  KEYWORD



Description: Criterion to select 1D ASCII output intervals, overrides out_every



Range   Default: default
default
Use IO::out_criterion
never
Never output
iteration
Output every so many iterations
divisor
Output if (iteration % out_every) == 0.
time
Output every that much coordinate time






out1d_d
Scope: private  BOOLEAN



Description: Do output along the diagonal



  Default: yes






out1d_dir
Scope: private  STRING



Description: Name of 1D ASCII output directory, overrides IO::out_dir



Range   Default: (none)
Empty: use IO::out_dir
.+
Not empty: directory name






out1d_dt
Scope: private  REAL



Description: How often to do 1D ASCII output, overrides IO::out_dt



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






out1d_every
Scope: private  INT



Description: How often to do 1D ASCII output, overrides out_every



Range   Default: -2
1:*
Output every so many time steps
-1:0
No output
-2
Use IO::out_every






out1d_vars
Scope: private  STRING



Description: Variables to output in 1D ASCII file format



Range   Default: (none)
List of group or variable names






out1d_x
Scope: private  BOOLEAN



Description: Do 1D IOASCII output in the x-direction



  Default: yes






out1d_xline_y
Scope: private  REAL



Description: y coordinate for 1D lines in x-direction



Range   Default: (none)
*:*






out1d_xline_yi
Scope: private  INT



Description: y-index (counting from 0) for 1D lines in x-direction



Range   Default: (none)
0:*






out1d_xline_z
Scope: private  REAL



Description: z coordinate for 1D lines in x-direction



Range   Default: (none)
*:*






out1d_xline_zi
Scope: private  INT



Description: z-index (counting from 0) for 1D lines in x-direction



Range   Default: (none)
0:*






out1d_y
Scope: private  BOOLEAN



Description: Do 1D IOASCII output in the y-direction



  Default: yes






out1d_yline_x
Scope: private  REAL



Description: x coordinate for 1D lines in y-direction



Range   Default: (none)
*:*






out1d_yline_xi
Scope: private  INT



Description: x-index (counting from 0) for 1D lines in y-direction



Range   Default: (none)
0:*






out1d_yline_z
Scope: private  REAL



Description: z coordinate for 1D lines in y-direction



Range   Default: (none)
*:*






out1d_yline_zi
Scope: private  INT



Description: z-index (counting from 0) for 1D lines in y-direction



Range   Default: (none)
0:*






out1d_z
Scope: private  BOOLEAN



Description: Do 1D IOASCII output in the z-direction



  Default: yes






out1d_zline_x
Scope: private  REAL



Description: x coordinate for 1D lines in z-direction



Range   Default: (none)
*:*






out1d_zline_xi
Scope: private  INT



Description: x-index (counting from 0) for 1D lines in z-direction



Range   Default: (none)
0:*






out1d_zline_y
Scope: private  REAL



Description: y coordinate for 1D lines in z-direction



Range   Default: (none)
*:*






out1d_zline_yi
Scope: private  INT



Description: y-index (counting from 0) for 1D lines in z-direction



Range   Default: (none)
0:*






out2d_criterion
Scope: private  KEYWORD



Description: Criterion to select 2D ASCII output intervals, overrides out_every



Range   Default: default
default
Use IO::out_criterion
never
Never output
iteration
Output every so many iterations
divisor
Output if (iteration % out_every) == 0.
time
Output every that much coordinate time






out2d_dir
Scope: private  STRING



Description: Name of 2D ASCII output directory, overrides IO::out_dir



Range   Default: (none)
Empty: use IO::out_dir
.+
Not empty: directory name






out2d_dt
Scope: private  REAL



Description: How often to do 2D ASCII output, overrides IO::out_dt



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






out2d_every
Scope: private  INT



Description: How often to do 2D ASCII output, overrides out_every



Range   Default: -2
1:*
Output every so many time steps
-1:0
No output
-2
Use IO::out_every






out2d_vars
Scope: private  STRING



Description: Variables to output in 2D ASCII file format



Range   Default: (none)
List of group or variable names






out2d_xy
Scope: private  BOOLEAN



Description: Do 2D IOASCII output in the xy-direction



  Default: yes






out2d_xyplane_z
Scope: private  REAL



Description: z coordinate for 2D planes in xy-direction



Range   Default: (none)
*:*






out2d_xyplane_zi
Scope: private  INT



Description: z-index (counting from 0) for 2D planes in xy-direction



Range   Default: (none)
0:*






out2d_xz
Scope: private  BOOLEAN



Description: Do 2D IOASCII output in the xz-direction



  Default: yes






out2d_xzplane_y
Scope: private  REAL



Description: y coordinate for 2D planes in xz-direction



Range   Default: (none)
*:*






out2d_xzplane_yi
Scope: private  INT



Description: y-index (counting from 0) for 2D planes in xz-direction



Range   Default: (none)
0:*






out2d_yz
Scope: private  BOOLEAN



Description: Do 2D IOASCII output in the yz-direction



  Default: yes






out2d_yzplane_x
Scope: private  REAL



Description: x coordinate for 2D planes in yz-direction



Range   Default: (none)
*:*






out2d_yzplane_xi
Scope: private  INT



Description: x-index (counting from 0) for 2D planes in yz-direction



Range   Default: (none)
0:*






out3d_criterion
Scope: private  KEYWORD



Description: Criterion to select 3D ASCII output intervals, overrides out_every



Range   Default: default
default
Use IO::out_criterion
never
Never output
iteration
Output every so many iterations
divisor
Output if (iteration % out_every) == 0.
time
Output every that much coordinate time






out3d_dir
Scope: private  STRING



Description: Name of 3D ASCII output directory, overrides IO::out_dir



Range   Default: (none)
Empty: use IO::out_dir
.+
Not empty: directory name






out3d_dt
Scope: private  REAL



Description: How often to do 3D ASCII output, overrides IO::out_dt



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






out3d_every
Scope: private  INT



Description: How often to do 3D ASCII output, overrides out_every



Range   Default: -2
1:*
Output every so many time steps
-1:0
No output
-2
Use IO::out_every






out3d_ghosts
Scope: private  BOOLEAN



Description: Output ghost zones (DEPRECATED)



  Default: yes






out3d_outer_ghosts
Scope: private  BOOLEAN



Description: Output outer boundary zones (assuming that there are nghostzones boundary points) (DEPRECATED)



  Default: yes






out3d_vars
Scope: private  STRING



Description: Variables to output in 3D ASCII file format



Range   Default: (none)
List of group or variable names






out_precision
Scope: private  INT



Description: How many digits to output floating-point numbers with



Range   Default: 15
0:*
Number of precision digits






output_all_timelevels
Scope: private  BOOLEAN



Description: Output all timelevels instead of only the current



  Default: no






output_boundary_points
Scope: private  BOOLEAN



Description: Output outer boundary points (assuming that there are nghostzones boundary points)



  Default: yes






output_ghost_points
Scope: private  BOOLEAN



Description: Output ghost points



  Default: yes






output_symmetry_points
Scope: private  BOOLEAN



Description: Output symmetry points (assuming that there are nghostzones symmetry points)



  Default: yes






separate_components
Scope: private  BOOLEAN



Description: Separate grid components in the output file by additional empty lines



  Default: no






separate_grids
Scope: private  BOOLEAN



Description: Separate grid levels in the output file by additional empty lines



  Default: yes






use_grid_coordinates
Scope: private  BOOLEAN



Description: Use grid coordinate grid functions to obtain coordinate locations



  Default: no






new_filename_scheme
Scope: shared from IO BOOLEAN






out_criterion
Scope: shared from IO KEYWORD






out_dir
Scope: shared from IO STRING






out_dt
Scope: shared from IO REAL






out_every
Scope: shared from IO INT






out_fileinfo
Scope: shared from IO KEYWORD






out_group_separator
Scope: shared from IO STRING






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



6 Interfaces

General

Implements:

ioascii

Grid Variables

6.0.1 PRIVATE GROUPS




  Group Names    Variable Names    Details   




last_output_iteration   compact0
last_output_iteration   dimensions0
  distributionCONSTANT
  group typeSCALAR
  timelevels1
 vararray_size4
 variable typeINT




last_output_time   compact0
last_output_time   dimensions0
  distributionCONSTANT
  group typeSCALAR
  timelevels1
 vararray_size4
 variable typeREAL




this_iteration   compact0
this_iteration   dimensions0
  distributionCONSTANT
  group typeSCALAR
  timelevels1
 vararray_size4
 variable typeINT




Uses header:

Timer.hh

carpet.hh

dist.hh

vect.hh

data.hh

gdata.hh

gf.hh

ggf.hh

typecase.hh

typeprops.hh

7 Schedule

This section lists all the variables which are assigned storage by thorn Carpet/CarpetIOASCII. 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:  
last_output_iteration last_output_time this_iteration 
   

Scheduled Functions

CCTK_STARTUP

  carpetioasciistartup

  startup routine

 

 After: ioutil_startup
 Language:c
 Options: global
 Type: function

CCTK_INITIAL

  carpetioasciiinit

  initialisation routine

 

 Language:c
 Options: global
 Type: function