Importing External Data into Cactus with IOFlexIO

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

The following description explains the IEEEIO file layout of an unchunked datafile which thorn IOFlexIO expects in order to restore Cactus variables from it properly. There is also a well-documented example C program provided (IOFlexIO/doc/CreateIOFlexIOdatafile.c) which illustrates how to create a datafile with IEEEIO 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 IEEEIO file.

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 IOFlexIO to savely match it against a specific Cactus variable. For that reason, the variable's name, its groupname, its grouptype, the timelevel to restore, 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 attached as attributes to the very first dataset in the file. 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.ieee in IEEEIO file layout which contains a single dataset named "grid::x", with groupname "grid::coordinates", grouptype CCTK_GF (thus identifying the variable as a grid function), the timelevel to restore set to 0, 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

  ioinfo -showattrdata x.ieee

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