xx CarpetIOASCII

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 CarpetIOASCIIxI/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 CarpetIOASCIIxParameters

The most important parameters to control the CarpetIOASCIIxI/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.

IOASCII::out[0-3]Dxevery (steerable)

How often to do periodic CarpetIOASCIIxoutput. If this parameter is set in the parameter file, it will override the setting of the shared IO::outxevery parameter. The output frequency can also be set for individual variables using the outxevery option in an option string appended to the

IOASCII::out[0-3]Dxvars parameter.

IOASCII::out[0-3]Dxdt (steerable)

output in intervals of that much coordinate time (overwrites IO::outxdt)

IOASCII::out[0-3]Dxcriterion (steerable)

criterion to select output intervals (overwrites IO::outxcriterion)

IOASCII::out[0-3]Dxvars (steerable)

The list of variables to output using the CarpetIOASCIIxI/O method. The variables must be given by their fully qualified variable or group name. The special keyword all requests CarpetIOASCIIxoutput for all variables. Multiple names must be separated by whitespaces.

Each group/variable name can have an option string attached in which you can specify a different output frequency for that individual variable, or a set of individual refinement levels to be output, eg.

xxIOASCII::out1D_varsx=x"wavetoy::phi{xout_everyx=x4xrefinement_levelsx=x{x1x2x}x}"

IOASCII::out[0-3]Dxdir

The directory in which to place the CarpetIOASCIIxoutput files. If the directory doesn’t exist at startup it will be created. If this parameter is set to an empty string CarpetIOASCIIxoutput will go to the standard output directory as specified in IO::outxdir.

IOASCII::outxprecision (steerable)

How many digits to output floating-point numbers with (overwrites IO::outxprecision).

IOASCII::onexfilexperxgroup

Write one output file per group instead of per variable.

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 CCTKxOutputVar*() 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 CCTKxOutputVar*() must be scheduled in level mode.

If output for a variable is required also for intermediate timesteps this can be achieved by calling CCTKxOutputVarAs*() 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

carpet2sdf A program to convert to a format suitable for the ser program written by M. Choptuik,

carpet2xgraph A program to convert to a format suitable for the xgraph or ygraph packages of P. Walker and D. Pollney,

Carpet2ygraph.pl A perl script to convert to a format suitable for the xgraph or ygraph packages of P. Walker and D. Pollney.

Carpet2ygraph.pl An improved version of the previous script.

mergeCarpetIOASCII.pl A perl script to remove duplicate datasets from file(s).

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

11compactxformat 10Scope: privatex01 BOOLEAN

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

11                   10  x01  Default: no

11

11onexfilexperxgroup 10Scope: privatex01  BOOLEAN

11Description: Write one file per group instead of per variable

11                   10  x01  Default: no

11

11out0dxcriterion  10Scope: privatex01  KEYWORD

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

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

11

11out0dxdir  10Scope: privatex01  STRING

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

11 Range 10 x01 Default: (none)
11ˆ$  10Empty: use IO::outxdir
11.+  10Not empty: directory name

11

11out0dxdt  10Scope: privatex01  REAL

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

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

11out0dxevery  10Scope: privatex01  INT

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

11 Range 10 x01 Default: -2
111:*  10Output every so many time steps
11-1:0  10No output
11-2  10Use IO::outxevery

11

11out0dxpointxx  10Scope: privatex01  REAL

11Description: x coordinate for 0D points

11  Range  10  x01  Default: (none)

11*:*  10

11

11out0dxpointxxi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11out0dxpointxy  10Scope: privatex01  REAL

11Description: y coordinate for 0D points

11  Range  10  x01  Default: (none)

11*:*  10

11

11out0dxpointxyi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11

11out0dxpointxz  10Scope: privatex01  REAL

11Description: z coordinate for 0D points

11  Range  10  x01  Default: (none)

11*:*  10

11

11out0dxpointxzi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11

11out0dxvars  10Scope: privatex01  STRING

11Description: Variables to output in 0D ASCII file format

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

11

11out1dxcriterion  10Scope: privatex01  KEYWORD

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

11 Range 10 x01 Default: default
11default  10Use IO::outxcriterion
11never  10Never output
11iteration  10Output every so many iterations
11divisor  10Output if (iteration % outxevery) == 0.
11time  10Output every that much coordinate time

11

11out1dxd  10Scope: privatex01  BOOLEAN

11Description: Do output along the diagonal

11                   10  x01  Default: yes

11

11out1dxdir  10Scope: privatex01  STRING

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

11 Range 10 x01 Default: (none)
11ˆ$  10Empty: use IO::outxdir
11.+  10Not empty: directory name

11

11out1dxdt  10Scope: privatex01  REAL

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

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

11out1dxevery  10Scope: privatex01  INT

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

11 Range 10 x01 Default: -2
111:*  10Output every so many time steps
11-1:0  10No output
11-2  10Use IO::outxevery

11

11out1dxvars  10Scope: privatex01  STRING

11Description: Variables to output in 1D ASCII file format

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

11

11out1dxx  10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: yes

11

11out1dxxlinexy  10Scope: privatex01  REAL

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

11  Range  10  x01  Default: (none)

11*:*  10

11

11out1dxxlinexyi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11

11out1dxxlinexz  10Scope: privatex01  REAL

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

11  Range  10  x01  Default: (none)

11*:*  10

11

11out1dxxlinexzi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11

11out1dxy  10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: yes

11

11out1dxylinexx  10Scope: privatex01  REAL

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

11  Range  10  x01  Default: (none)

11*:*  10

11

11out1dxylinexxi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11

11out1dxylinexz  10Scope: privatex01  REAL

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

11  Range  10  x01  Default: (none)

11*:*  10

11out1dxylinexzi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11

11out1dxz  10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: yes

11

11out1dxzlinexx  10Scope: privatex01  REAL

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

11  Range  10  x01  Default: (none)

11*:*  10

11

11out1dxzlinexxi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11

11out1dxzlinexy  10Scope: privatex01  REAL

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

11  Range  10  x01  Default: (none)

11*:*  10

11

11out1dxzlinexyi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11

11out2dxcriterion  10Scope: privatex01  KEYWORD

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

11 Range 10 x01 Default: default
11default  10Use IO::outxcriterion
11never  10Never output
11iteration  10Output every so many iterations
11divisor  10Output if (iteration % outxevery) == 0.
11time  10Output every that much coordinate time

11

11out2dxdir  10Scope: privatex01  STRING

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

11 Range 10 x01 Default: (none)
11ˆ$  10Empty: use IO::outxdir
11.+  10Not empty: directory name

11

11out2dxdt  10Scope: privatex01  REAL

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

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

11out2dxevery  10Scope: privatex01  INT

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

11 Range 10 x01 Default: -2
111:*  10Output every so many time steps
11-1:0  10No output
11-2  10Use IO::outxevery

11

11out2dxvars  10Scope: privatex01  STRING

11Description: Variables to output in 2D ASCII file format

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

11

11out2dxxy  10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: yes

11

11out2dxxyplanexz  10Scope: privatex01  REAL

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

11  Range  10  x01  Default: (none)

11*:*  10

11

11out2dxxyplanexzi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11

11out2dxxz  10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: yes

11

11out2dxxzplanexy  10Scope: privatex01  REAL

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

11  Range  10  x01  Default: (none)

11*:*  10

11

11out2dxxzplanexyi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11

11out2dxyz  10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: yes

11

11out2dxyzplanexx  10Scope: privatex01  REAL

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

11  Range  10  x01  Default: (none)

11*:*  10

11

11out2dxyzplanexxi  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)

110:*  10

11out3dxcriterion  10Scope: privatex01  KEYWORD

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

11 Range 10 x01 Default: default
11default  10Use IO::outxcriterion
11never  10Never output
11iteration  10Output every so many iterations
11divisor  10Output if (iteration % outxevery) == 0.
11time  10Output every that much coordinate time

11

11out3dxdir  10Scope: privatex01  STRING

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

11 Range 10 x01 Default: (none)
11ˆ$  10Empty: use IO::outxdir
11.+  10Not empty: directory name

11

11out3dxdt  10Scope: privatex01  REAL

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

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

11out3dxevery  10Scope: privatex01  INT

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

11 Range 10 x01 Default: -2
111:*  10Output every so many time steps
11-1:0  10No output
11-2  10Use IO::outxevery

11

11out3dxghosts  10Scope: privatex01  BOOLEAN

11Description: Output ghost zones (DEPRECATED)

11                   10  x01  Default: yes

11

11out3dxouterxghosts 10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: yes

11

11out3dxvars  10Scope: privatex01  STRING

11Description: Variables to output in 3D ASCII file format

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

11

11outxprecision  10Scope: privatex01  INT

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

11 Range 10 x01 Default: 15
110:*  10Number of precision digits

11

11outputxallxtimelevels 10Scope: privatex01  BOOLEAN

11Description: Output all timelevels instead of only the current

11                   10  x01  Default: no

11outputxboundaryxpoints 10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: yes

11

11outputxghostxpoints 10Scope: privatex01  BOOLEAN

11Description: Output ghost points

11                   10  x01  Default: yes

11

11outputxsymmetryxpoints 10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: yes

11

11separatexcomponents 10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: no

11

11separatexgrids  10Scope: privatex01  BOOLEAN

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

11                   10  x01  Default: yes

11

11usexgridxcoordinates 10Scope: privatex01  BOOLEAN

11Description: Use grid coordinate grid functions to obtain coordinate locations

11                   10  x01  Default: no

11

11newxfilenamexscheme 10Scope: shared from IOx01BOOLEAN

11

11outxcriterion  10Scope: shared from IOx01KEYWORD

11

11outxdir  10Scope: shared from IOx01STRING

11

11outxdt  10Scope: shared from IOx01REAL

11

11outxevery  10Scope: shared from IOx01INT

11

11outxfileinfo  10Scope: shared from IOx01KEYWORD

11

11outxgroupxseparator 10Scope: shared from IOx01STRING

11

11outxxlinexy  10Scope: shared from IOx01REAL

11

11outxxlinexyi  10Scope: shared from IOx01INT

11outxxlinexz  10Scope: shared from IOx01REAL

11

11outxxlinexzi  10Scope: shared from IOx01INT

11

11outxxyplanexz  10Scope: shared from IOx01REAL

11

11outxxyplanexzi  10Scope: shared from IOx01INT

11

11outxxzplanexy  10Scope: shared from IOx01REAL

11

11outxxzplanexyi  10Scope: shared from IOx01INT

11

11outxylinexx  10Scope: shared from IOx01REAL

11

11outxylinexxi  10Scope: shared from IOx01INT

11

11outxylinexz  10Scope: shared from IOx01REAL

11

11outxylinexzi  10Scope: shared from IOx01INT

11

11outxyzplanexx  10Scope: shared from IOx01REAL

11

11outxyzplanexxi  10Scope: shared from IOx01INT

11

11outxzlinexx  10Scope: shared from IOx01REAL

11

11outxzlinexxi  10Scope: shared from IOx01INT

11

11outxzlinexy  10Scope: shared from IOx01REAL

11

11outxzlinexyi  10Scope: shared from IOx01INT

11

11strictxioxparameterxcheck 10Scope: shared from IOx01BOOLEAN

11verbose  10Scope: shared from IOx01KEYWORD

11

6 Interfaces

General Implements: ioascii

Grid Variables

6.0.1 PRIVATE GROUPS

11x Group Names x10x Variable Names xx01 Details x11x
11lastxoutputxiteration10 lastxoutputxiteration x01  compact110
11                  10  x01 dimensions110
11                  10  x01 distribution11CONSTANT
11                  10  x01 group type11SCALAR
11                  10  x01 timelevels111
11                  10  x01vararrayxsize114
11                  10  x01variable type11INT
11 lastxoutputxtime 10 lastxoutputxtime x01  compact110
11                  10  x01 dimensions110
11                  10  x01 distribution11CONSTANT
11                  10  x01 group type11SCALAR
11                  10  x01 timelevels111
11                  10  x01vararrayxsize114
11                  10  x01variable type11REAL
11 thisxiteration 10 thisxiteration x01  compact110
11                  10  x01 dimensions110
11                  10  x01 distribution11CONSTANT
11                  10  x01 group type11SCALAR
11                  10  x01 timelevels111
11                  10  x01vararrayxsize114
11                  10  x01variable type11INT

11

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 x

11Always:  11x
11lastxoutputxiteration lastxoutputxtime thisxiteration11x

11x  11x

11

Scheduled Functions

CCTKxSTARTUP x carpetioasciistartup x startup routine x

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

11

CCTKxINITIAL x carpetioasciiinit x initialisation routine x

11x11Language:11c
11 x 11Options: 11global
11 x 11Type: 11function
11 x 11Writes: 11carpetioascii::lastxoutputxiteration
11 x 11x  11lastxoutputxtime
11 x 11x  11thisxiteration