Serial File I/O

Sidre provides file I/O to HDF5 files and file handles and to JSON files. Serial I/O is accomplished using methods of the Group class; parallel I/O is done using the IOManager class.

HDF5 is an optional dependency for Sidre. Sidre APIs that rely on HDF5 will be available only if Sidre was compiled with HDF5 support. The CMake variable that controls dependency on HDF5 is AXOM_USE_HDF5, defined in the file axom/config.hpp.

File I/O using the Group class

The Group class provides methods: save(), load(), and loadExternalData() methods. Each method can be called with a file name or an HDF5 handle. The save() and load() methods allow users to specify a protocol, which indicates how the operation should be performed and what file format to use. The loadExternalData() method takes no protocol argument since it is only used with the sidre_hdf5 protocol. The save() method can also take a pointer to an Attribute object. If the attribute pointer is null, all views are saved. If a non-null attribute pointer is given, only views with that attribute set will be saved.

The load() method retrieves the hierarchical data structure stored in the file and creates groups, views, and attributes to represent the hierarchy with its root in the group on which the method is called. By default, the contents of the group are destroyed prior to reading the file contents. This can be suppressed by passing a Boolean value of true as the preserve_contents argument to the load() method, resulting in the current group subtree being merged with the file contents.

Usage of the save() and load() methods is shown in the following example.

  // Save the data store to a file,
  // saving all Views
  ds->getRoot()->save(filename, protocol);
  // Delete the data hierarchy under the root, then load it from the file
  ds->getRoot()->load(filename, protocol);
  Group* additional = ds->getRoot()->createGroup("additional");
  additional->createGroup("yetanother");
  // Load another copy of the data store into the "additional" group
  // without first clearing all its contents
  std::string groupname;
  additional->load(filename, protocol, true, groupname);

The loadExternalData() method is used to read “external” data from an HDF5 file created with the sidre_hdf5 protocol. This is data referred to by external views. Such views refer to data that is not stored in Sidre buffers but in an external data allocation.

Overloads of the save() and load() methods that take HDF5 handles and the loadExternalData() method are used to implement parallel I/O through the Sidre IOManager class.

Please see Sidre API Documentation for more detailed description of these Group class methods and the Sidre I/O protocols that can be used with them.