Importing External Data Into Cactus With IOHDF5

In order to import external data into Cactus (eg. to initialize some variable) you first need to convert this data into an HDF5 datafile which then can be processed by the registered recovery routine of thorn IOHDF5.

The following description explains the HDF5 file layout of an unchunked datafile which thorn IOHDF5 expects in order to restore Cactus variables from it properly. There is also a well-documented example C program provided (IOHDF5/doc/CreateIOHDF5datafile.c) which illustrates how to create a datafile with IOHDF5 file layout. This working example can be used as a template for building your own data converter program.

1. Actual data is stored as multidimensional datasets in an HDF5 file. There is no nested grouping structure, every dataset is located in the root group.
   A dataset's name must match the following naming pattern which guarantees to generate unique names:

     "<full variable name> timelevel <timelevel> at iteration <iteration>"
   

   IOHDF5's recovery routine parses a dataset's name according to this pattern to determine the Cactus variable to restore, along with its timelevel. The iteration number is just informative and not needed here.

2. The type of your data as well as its dimensions are already inherited by a dataset itself as metainformation. But this is not enough for IOHDF5 to safely match it against a specific Cactus variable. For that reason, the variable's groupname, its grouptype, and the total number of timelevels must be attached to every dataset as attribute information.

3. Finally, the recovery routine needs to know how the datafile to recover from was created:
   • Does the file contain chunked or unchunked data ?
   • How many processors were used to produce the data ?
   • How many I/O processors were used to write the data ?
   • What Cactus version is this datafile compatible with ?
   Such information is put into as attributes into a group named "Global Attributes". Since we assume unchunked data here the processor information isn't relevant -- unchunked data can be fed back into a Cactus simulation running on an arbitrary number of processors.
   The Cactus version ID must be present to indicate that grid variables with multiple timelevels should be recovered following the new timelevel scheme (as introduced in Cactus beta 10).

The example C program goes through all of these steps and creates a datafile x.h5 in IOHDF5 file layout which contains a single dataset named "grid::x timelevel 0 at iteration 0", with groupname "grid::coordinates", grouptype CCTK_GF (thus identifying the variable as a grid function), and the total number of timelevels set to 1.

The global attributes are set to "unchunked" $=$ "yes", nprocs $=$ 1, and ioproc_every $=$ 1.

Once you've built and ran the program you can easily verify if it worked properly with

  h5dump x.h5

which lists all objects in the datafile along with their values. It will also dump the contents of the 3D dataset. Since it only contains zeros it would probably not make much sense to feed this datafile into Cactus for initializing your x coordinate grid function :-)