Reading Data from Files into Cactus

The very same routines which implement checkpointing/recovery functionality in the IOHDF5 and IOFlexIO thorns are also used to provide file reader capabilities within Cactus. They enable users to read variables, whose contents were written to files in HDF5 or IEEEIO data format, back into Cactus at a later time. This is especially useful if compute-intensive initial data is calculated only once and stored in a file. Such data can then be read back in at startup and immediately used by following evolution runs.

The following IOUtil parameters exist to specify what variables should be read from file(s) as initial data:

• IO::filereader_ID_dir
  root directory for files to be read
• IO::filereader_ID_files
  list of files to read in as initial data (multiple filenames must be separated by spaces)
  The same file naming conventions (what I/O mode used, which iteration number) apply as for checkpoint files.
• IO::filereader_ID_vars
  list of CCTK variables to read in from the given initial data files (variables are identified by their full name, multiple variable names must be separated by spaces)
  This is useful if a datafile contains multiple variables but only some of them should be read. Thus it is possible to recover distinguished variables from a full checkpoint file.
  Note that if the file contains several timesteps of the same variable only the last one is taken by default. This can be changed by adding an option string with the key cctk_iteration and an associated integer scalar value to the variable name denoting the iteration number to choose, like in IO::filereader_ID_vars = "wavetoy::phi{ cctk_iteration = 10 }".

Thorn IOUtil also provides a filereader API which can be called by any application thorn at any time. It gets passed the equivalent information to the filereader parameters, plus a pointer to the underlying CCTK grid hierarchy. The return code denotes the total number of variables recovered by the filereader.

C API:

  #include "CactusBase/IOUtil/src/ioutil_CheckpointRecovery.h"


  int IOUtil_RecoverVarsFromDatafiles (cGH *GH,
                                       const char *in_files,
                                       const char *in_vars);

Fortran API:

  call IOUtil_RecoverVarsFromDatafiles (result, GH, in_files, in_vars)

    integer       result
    CCTK_POINTER  GH
    character*(*) in_files
    character*(*) in_vars

If data is to be imported from files which were not created by IOHDF5 or IOFlexIO it needs to be converted first into the appropriate HDF5 or IEEEIO file format and the file layout which either one of these thorns uses. This is described in detail in the thorns' documentation, along with a simple C source file which can be used as a template to build your own data converter program.