3.1 Binary Structured Files

Most of the data files used by NEMO share a common low level binary file structure, which can be viewed as a sequence of tagged data items. Special symbols are defined to group these items hierarchically into sets. Data items are typically scalar values or homogeneous arrays constructed from elementary C data types, but the programmer can also add more complex structures, such as C's struct structure definition, or any user defined data structure. In this last case tagging by type is not possible anymore, and support for a machine independent format is not guaranteed. Using such constructs is not recommended if the data needs to be portable accross platforms.

The hierarchical structure of a binary file in this general format can be viewed in human-readable format at the terminal using a special program, tsf ("type structured file"). Its counterpart, rsf ("read structured file"), converts such human-readable files (in that special ASCII Structured File format, or ASF) into binary structured files (BSF). In principle it is hence possible to transfer data files between different types of computers using rsf and tsf (see examples in Section ). ^3.3

Let us start with a small example: With the NEMO program mkplummer we first create an N-body realization of a spherical Plummer model:

    1% mkplummer i001.dat 1024

Note that we made use of the shortcut that out= and nbody= are the first two program keywords, and they were assigned their value by position rather than by associated name. We can now display the contents of the binary file i001.dat with tsf:

    2% tsf i001.dat

    char Headline[33] "set_xrandom: seed used 706921861"
    char History[36] "mkplummer i001.dat 1024 VERSION=2.5"
    set SnapShot                                                            
      set Parameters                                                        
        int Nobj 01750
        double Time 0.00000                                                 
      tes                                                                   
      set Particles                                                         
        int CoordSystem 0201402                                             
        double Mass[1024] 0.00195313 0.00195313 0.00195313
          0.00195313 0.00195313 0.00195313 0.00195313 0.00195313
          0.00195313 0.00195313 0.00195313 0.00195313 0.00195313
          0.00195313 0.00195313 0.00195313 0.00195313 0.00195313
          . . .
        double PhaseSpace[1024][2][3] 4.92932 0.425103 -0.474249
          0.342025 -0.112242 4.60796 -0.00388599 -0.389558 -0.958787
          0.220561 0.213904 3.47561 0.0176012 1.22146 -0.903484
          -0.705422 4.26963 -0.263561 1.04382 -0.199518 -0.480749
          . . .                                                             
      tes                                                                   
    tes

This is an example of a data-file from the N-body group, and consists of a single snapshot at time=0.0. This snapshot, with 1024 bodies with double precision masses and full 6 dimensional phase space coordinates, totals 57606 bytes, whereas a straight dump of only the essential information would have been 57344 bytes, a mere 0.5% overhead. The overhead will be larger with small amounts of data, e.g. diagnostics in an N-body simulation, or small N-body snapshots.

Besides some parameters in the 'Parameters' set, it consists of a 'Particles' set, where (along the type of coordinate system) all the masses and phase space coordinates of all particles are defined. Note the convention of integers starting with a '0' in octal representation. This is done for portability reasons.

A remark about online help: NEMO also uses the man(5) format for more detailed online help, although the inline help (system help= keyword) is most of the times sufficient enough to remind a novice user of the keywords and their meaning. The man command is a last resort, if more detailed information and examples are needed.

    3% man tsf

Note that, since the online manual page is a different file from the source code, information in the manual page can easily get outdated, and the inline (help=) help, although very brief, is more likely to be up to date since it is generated from the source code (executable) itself:

    4% tsf help=h
    in               : input file name  [???]
    maxprec          : print nums with max precision  [false]
    maxline          : max lines per item  [4]
    allline          : print all lines (overrides maxline)  [false]
    indent           : indentation of compound items  [2]
    margin           : righthand margin  [72]
    item             : Select specific item []
    xml              : output data in XML format? (experimental) [f]
    octal            : Force integer output in octal again? [f]
    VERSION          : 29-aug-02 PJT  [3.1]