Overview

TPFileConvert.C - a binary to HDF5 converter for tracer particle data.

Author: Devin W. Silvia Date: February 12, 2009.  Affiliation:
CASA/University of CO, Boulder Homepage: http://hub.yt-project.org/

I. INTRODUCTION

As it currently stands, in Enzo runs that make use of tracer particles
all of the tracer particle data is output as streaming binary files.
While this is the fastest and cheapest way to output the particle data
(by avoiding extra HDF5 writes and minimizing file size), it is not
terribly useful from an analysis standpoint.  To remedy this
situation, TPFileConvert.C reads in the standard tracer particle
files, parses the binary stream, and then outputs HDF5 files loaded
with the data from the simulation in the standard Enzo practice of
having an HDF5 file for each data dump.  The data can then be read and
analyzed using the simulator's code of choice.

This code was built off of a chunk of core code first written by Brian
W. O'Shea.

II. RUNNING TPFileConvert.C

TPFileConvert.C is a C++ code and as such must be compiled before it
can be run.  An example of how to compile the code is the following:

g++ -I/opt/local/include -L/opt/local/lib -lhdf5 TPFileConvert.C -o tp.exe

Note the -I and -L flags in the call to the g++ compiler.  Since
TPFileConvert.C creates and writes to HDF5 files, you must have HDF5
installed on your machine and you must tell the compiler where the
code can find the HDF5 libraries.  Note that you may need to add the
compiler flag "-DH5_USE_16_API" if you are using a newer (v1.8+)
version of HDF5. In addition, g++ can be substituted with whatever C++
compiler your machine uses.

Once the code has been compiled you will find that a 'tp.exe'
executable has been created.  At this point, all that needs to be done
is the following:

./tp.exe

This will run the executable and carry out the binary to HDF5
conversion.

III. USER DEFINED VARIABLES IN TPFileConvert.C

It is important to mention that as it stands currently,
TPFileConvert.C requires several flags to be preset by the user before
compiling to ensure successful conversion.

   1) ENZO_INTERNAL_FLOAT and HDF5_MEM_FLOAT -- these two flags (which
   need to agree) should correspond to Enzo's internal floating-point
   precision during simulation runtime (i.e., the simulation that generated
   the tracer particle data you're using).  If this is not set correctly,
   TPFileConvert.C will incorrectly step through the files and exceedingly
   puzzling results will occur.

   2) ENZO_INTERNAL_INT and HDF5_MEM_INT -- as with the floating-point flags,
   these correspond to Enzo's internal integer precision during simulation 
   runtime.

   3) SIMULATION_GRIDRANK -- this flag tells TPFileConvert.C what
   the dimensionality of the Enzo simulation is.  This should be
   equal to TopGridRank in the Enzo parameter file.

   4) TP_VELOCITY -- this flag tells TPFileConvert.C whether or not
   the user wants tracer particle velocity data to be included in the
   HDF5 files.  TP_VELOCITY can only be used if the binary data files
   actually contain tracer particle velocity data.  If the user
   doesn't wish to have the velocity information included in the
   created HDF5 files or there is no velocity information included
   within the binary data files then this flag should be set to
   NO_TP_VELOCITY.

   5) TOTALPROCS -- this defines the number of processors that the
   simulation was run with as this corresponds to the number of TP
   binary files that need to be read.  Set this to be the same as the
   number of processors that were used to ensure successful
   conversion.

If these variables are not set correctly, then you will undoubtedly
get spurious results -- check these first if the code errors.

IV. TPFileConvert.C OUTPUT

When the executable is run, information about the progress of the file
conversion will print to the screen.  This will begin with which
binary file the code is currently operating on as well as the names of
the files it creates for that processor and ends with the names of the
processor-combined HDF5 files for each data dump.

Note that the files which the code creates for each processor are only
needed as an intermediate step and are deleted when the code finishes.
The final output consists of files that follow the format of
TPDD####.h5 where #### will indicate which data dump that file
corresponds to.

Each HDF5 file will contain arrays of particle data that should be as
long as the number of tracer particles used in the simulation.  These
arrays are named densvals, tempvals, xvals, yvals, and zvals which
correspond to density, temperature, x-position, y-position,
z-position.  If the user has also included velocity data then these
will be named vxvals, vyvals, and vzvals which are, not surprisingly,
x-velocity, y-velocity, and z-velocity.

The output files should be easily read by whatever analysis language
is desired provided the correct HDF5 file reading commands are used.