Table of Contents

Name

tabtos - convert structured ASCII tables into snapshot format

Synopsis

tabtos in=ascii_file out=snap_file [parameter=value] ...

Description

tabtos converts ASCII tables into snapshot(5NEMO) format. These tables can be structured as well as unstructured tables. There is a control parameter (options=scan) with which one may be able to figure out the structure of a file. For binary files, there are several examples, as well the more generic binsnap(1NEMO) .

Structured tables consist of a small (though optional) header, that normally contains parameters like the number of bodies, the time of the snapshot etc., and one or more blocks (sections) of homogeneous tables, their length equal the number of bodies in the snapshot and their width as specified by the user from the variables expected to be present in those blocks. Examples will be shown below.

Unstructured files (i.e. without a header) can also be processed if the user specifies how many bodies are present per snapshot. If even that is not done, the number of lines in the file (corrected for the number of times and blocks specified) is used to derive the number of bodies. Although at least one block must be present, if no times are specified, the number of snapshots is then assumed to be one. See examples below.

By default tabtos does not handle comment lines (lines starting with #) gracefully at all, see options=comment or options=history below how to deal with his. If you use these options, automatically determining nbody will not work, and either header= or nbody= needs to be used.

Parameters

The following parameters are recognized in any order if the keyword is also given:
in=ascii_file
Input file name (ascii table/structure) No default.
out=snap_file
Output file name (snapshot). No default.
header=var1,var2,...
A list of variables that are present in the header, in the order given. They do not need to be present on the same line.

Recognized are: nbody, ndim, time, skip (-). If they do not appear in the header, their value should be set via the equivalent keyword (see below). The special value skip (or -) is allowed to skip header items that have no current meaning in parsing the data into snapshot format (e.g. SPH files have ngas, but this is currently not processed). Default: none supplied.

block1=var1,var2,...
A list of variables that are present in this block of nbody lines, in the order give.

Recognized are: mass, pos, vel, phase, acc, phi, dens, aux for real-valued and key for integer valued columns (see also snapshot(5NEMO) ). In addition, single elements from the ndim vector are recognized as x, y, z, vx, vy, vz, ax, ay, az. m is also recognized as mass, to be symmetric with the standard bodytrans(5NEMO) names. As before, the name skip (or -) can be used to skip a column. If the variable skip appears are the only item in a block, all nbody rows in that block are skipped, independant of the number of columns (NOTE: this cannot be done if options=wrap is used).

Structured ASCII tables can contain up to 9 separate blocks, currently all of them must have the same length, and be equal to the number of bodies, nbody. No default.

block2=var1,var2,...
See above, for 2nd block, if present. Default: not used.
block3=var1,var2,...
See above, for 3rd block, if present. Default: not used.
block4=var1,var2,...
See above, for 4th block, if present. Default: not used.
block5=var1,var2,...
See above, for 5th block, if present. Default: not used.
block6=var1,var2,...
See above, for 6th block, if present. Default: not used.
block7=var1,var2,...
See above, for 7th block, if present. Default: not used.
block8=var1,var2,...
See above, for 8th block, if present. Default: not used.
block9=var1,var2,...
See above, for 9th block, if present. Default: not used.
nbody=nbody
Number of bodies, if the header doesn’t supply it. If none supplied, neither through the header, nor using this keyword, it is derived from the number of lines in the file, corrected (divided) by the number of specified blocks (block#=) and the numbers of specified times. (times=). Default: not used.
ndim=NDIM
Dimension of pos,vel,acc arrays, if the header doesn’t supply it. The program can be compiled for NDIM=2 or 3, but they must match. If not specified, the program will assume it’s internal; default, NDIM. Default: not used.
times=t1,t2,...
Time(s) of snapshot(s), if the header doesn’t supply it. This can be a list of times, if multiple snapshot are being read. Implied do loops can be given, for example, 0:100:2.5 is a legal way to specify an array of 41 times (see nemoinp(1NEMO) ) Specifying times through this keyword not only overrides any header values, but also limits the maximum number of snapshot that are read (thus avoiding the dreaded fatal EOF error) One can also use options=time, in which case time is auto-incremented (by 1) for each snapshot. Default: not used.
options=
A list of options, needs exact match. scan the input file is merely scanned for regularity. It then prints the line numbers at which the number of columns changed. It’s a bit more informational than awk ’{print NF}’ | uniq. comment allows you to have comment lines in the file (lines that start with a # symbol). By default no comment lines are allowed. wrap allows, for each block, the expected numbers on a line to be wrapped over more than one line. The side-effect of this is that the next record in that same block starts immediately following the wrapped number. spill discards all numbers read from the last line to fill a record within a block, and hence negates the side-effect of the wrap option. time auto-increments time (by 1) as new snapshots are found. history uses comment lines and adds them to the data history (see history(3NEMO) ).
headline=
Random mumblage for humans, used to identify the snapshot. Default: not used.

Examples

To read in a single snapshot table with masses, (3D) positions and velocities in columns 1-7, with the number of bodies equals the number of rows in the table, you can use:
    % tabtos in=table out=snap block1=mass,pos,vel
To read in "205" formatted N-body snapshots (see also atos(1NEMO) ), with three seperate blocks of masses, positions and velocities, you can use:
    % tabtos in=table out=snap header=nbody,ndim,time \
            block1=mass block2=pos block3=vel
To read in "205" pure-SPH data (i.e. NGAS=NOBJ, see also atosph(1NEMO) ), in which the density is going to be stored in the mass slot, entropy/temperature in aux, potentials in phi, and masses and smoothing lengths are skipped, use:
    % tabtos in=table out=snap header=nbody,skip,ndim,time  \
            block1=skip block2=pos block3=vel block4=mass block5=aux \
            block6=skip block7=phi
Note: files with Ngas < Nobj cannot be processed (yet), since the blocks have different length. See atosph(1NEMO) .

205 Format

For a full explanation, see atos(1NEMO) , but below we list the two different popular "205" formats around (atos, and atosph)


format    header              blocks
atos    nbody,ndim,time      mass pos vel phi
atosph    nbody,ngas,ndim,time    mass pos vel rho temp hsph phi acc

Caveats

tabtos is very tolerant (sometimes too!) with respect to slight under- or over-specifications. It tries to write data, but only if it really gets stuck, the program is aborted. warning(3NEMO) messages should not be discarded, check them to see if they make sense. Otherwise what you think is correct data, may not have been parsed correctly. That’s life in the fast ASCII lane.

If no times specified, and the header= has no associated time, all snapshots will have the same time (0.0). A warning will be issued.

If both times specified, and the header= has an associated time, the header value will be overriden with the user specified values. Note that the number of specified times now determines the maximum number of snapshots that will be read, i.e. EOF may not be reached.

Although snapshots with varying amounts of particles can be read, there are many programs in NEMO which have difficulties if the first snapshot is not the largest one in that file.

Bugs

This is a complicated program to understand, but can often read complicated ascii files.

This program cannot parse fixed column files if they are not separated by whitespace.

Files with comment lines cannot be parsed. Use tabcomment(1NEMO) to delete them:

    tabcomment tab.in - delete=t | tabtos - snap.out ....
though the drawback of using a pipe in this example is that typically the keyword nbody= needs to be supplied.

See Also

atos(1NEMO) , atosph(1NEMO) , binsnap(1NEMO) , snapprint(1NEMO) , snapshot(5NEMO) , unfio(1NEMO)

Author

Peter Teuben

Update History


27-Aug-93    V1.0 Created, I finally broke down    Peter Teuben
30-aug-93    V1.1 added scan=                       PJT
25-oct-94    V1.2 options=scan|comment    PJT
2-nov-94    V1.2d added wrap/spill, fixed times= bug    PJT
19-aug-00    V1.3d fixed various TAB related problems    PJT
24-jan-02    V1.3f block10 now    PJT
29-jul-05    V1.4 added options=time to auto-inc time    PJT
14-nov-06    V1.5 added history option            PJT
18-jan-12    V1.5a  added dens(ity) option    JCL


Table of Contents