AXOM
Axom provides a robust, flexible software infrastructure for the development of multi-physics applications and computational tools.
axom::sidre::IOManager Class Reference

IOManager manages and organizes the I/O operations. More...

#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/develop/src/axom/sidre/spio/IOManager.hpp>

Public Member Functions

 IOManager (MPI_Comm com, bool use_scr=false)
 Constructor. More...
 
 ~IOManager ()
 Destructor. More...
 
void write (sidre::Group *group, int num_files, const std::string &file_base, const std::string &protocol, const std::string &tree_pattern="datagroup")
 write a Group to output files More...
 
void writeGroupToRootFile (sidre::Group *group, const std::string &file_name)
 write additional group to existing root file More...
 
void writeGroupToRootFileAtPath (sidre::Group *group, const std::string &file_name, const std::string &group_path)
 write additional group to a path inside an existing root file More...
 
void writeViewToRootFileAtPath (sidre::View *view, const std::string &file_name, const std::string &group_path)
 write additional group to a path inside an existing root file More...
 
void writeBlueprintIndexToRootFile (DataStore *datastore, const std::string &domain_path, const std::string &file_name, const std::string &mesh_path)
 write a Conduit Blueprint index to an existing root file More...
 
void read (sidre::Group *group, const std::string &root_file, const std::string &protocol, bool preserve_contents=false)
 read from input file More...
 
void read (sidre::Group *group, const std::string &root_file, bool preserve_contents=false)
 read from a root file More...
 
void loadExternalData (sidre::Group *group, const std::string &root_file)
 load external data into a group More...
 
int getNumFilesFromRoot (const std::string &root_file)
 gets the number of files in the dataset from the specified root file More...
 
int getNumGroupsFromRoot (const std::string &root_file)
 gets the number of groups in the dataset from the specified root file More...
 

Static Public Member Functions

static std::string correspondingRelayProtocol (const std::string &sidre_protocol)
 Finds conduit relay protocol corresponding to a sidre protocol. More...
 

Detailed Description

IOManager manages and organizes the I/O operations.

This class handles the bookkeeping and organizing tasks that must be done before calling Group's I/O methods. It uses IOBaton to control the parallel I/O operations, such that one rank at a time interacts with any particular output file.

Constructor & Destructor Documentation

◆ IOManager()

axom::sidre::IOManager::IOManager ( MPI_Comm  com,
bool  use_scr = false 
)

Constructor.

Parameters
comMPI communicator
use_scrUse SCR library for scalable I/O management. If true, the calling code must have already called SCR_Init() after MPI_Init().

◆ ~IOManager()

axom::sidre::IOManager::~IOManager ( )

Destructor.

Member Function Documentation

◆ write()

void axom::sidre::IOManager::write ( sidre::Group group,
int  num_files,
const std::string &  file_base,
const std::string &  protocol,
const std::string &  tree_pattern = "datagroup" 
)

write a Group to output files

The Group, including all of its child groups and views, is written to files according to the given protocol.

This is an MPI collective call that must be called on all ranks in the communicator used in this object's constructor.

valid protocols:

sidre_hdf5 sidre_conduit_json sidre_json

conduit_hdf5 conduit_bin conduit_json json

The output will consist of a root file and a subdirectory containing data output files. The name of the root file will be the file_base parameter with the suffix ".root" appended, while the subdirectory will have the file_base string as its name. Exception: If the file_base parameter is provided as a string ending in ".root", that string will be unchanged and used as the root file's name, while the subdirectory name will be the file_base string with the ".root" suffix removed from its end.

The file_base string must be identical on all ranks making this call. If it is not identical, a warning will be printed and the files produced here may not be useable in a subsequent call to IOManager::read().

Note
The sidre_hdf5 and conduit_hdf5 protocols are only available when Axom is configured with hdf5.
Parameters
groupGroup to write to output
num_filesnumber of output data files
file_basebase name for output files
protocolidentifies I/O protocol
tree_patternOptional tree pattern string placed in root file, to set search path for data in the output files

◆ writeGroupToRootFile()

void axom::sidre::IOManager::writeGroupToRootFile ( sidre::Group group,
const std::string &  file_name 
)

write additional group to existing root file

Should be called after write(). The native layout of the group will be added to the root file.

This may be called more than once to write multiple groups to the file.

This is not an MPI collective call. It writes one group from one rank to one root file.

This currently only works if the root file was created for protocol sidre_hdf5.

Parameters
groupGroup to add to root file
file_namename of existing root file

◆ writeGroupToRootFileAtPath()

void axom::sidre::IOManager::writeGroupToRootFileAtPath ( sidre::Group group,
const std::string &  file_name,
const std::string &  group_path 
)

write additional group to a path inside an existing root file

This should be called on an existing root file that already contains a Group, most likely from a previous call to writeGroupToRootFile.

group_path is a path that specifies a location somewhere in the native layout of a Group already in the file. The group added in this method will be stored as a child group of the group specified by the path.

This is not an MPI collective call. It writes one group from one rank to one root file.

This currently only works if the root file was created for protocol sidre_hdf5.

Parameters
groupGroup to add to root file
file_namename of existing root file
group_pathpath to a location within the root file

◆ writeViewToRootFileAtPath()

void axom::sidre::IOManager::writeViewToRootFileAtPath ( sidre::View view,
const std::string &  file_name,
const std::string &  group_path 
)

write additional group to a path inside an existing root file

This should be called on an existing root file that already contains a Group, most likely from a previous call to writeGroupToRootFile.

group_path is a path that specifies a location somewhere in the native layout of a Group already in the file. The view added in this method will be stored as a child view of the group specified by the path.

This is not an MPI collective call. It writes one view from one rank to one root file.

This currently only works if the root file was created for protocol sidre_hdf5.

Parameters
viewView to add to root file
file_namename of existing root file
group_pathpath to a location within the root file

◆ writeBlueprintIndexToRootFile()

void axom::sidre::IOManager::writeBlueprintIndexToRootFile ( DataStore datastore,
const std::string &  domain_path,
const std::string &  file_name,
const std::string &  mesh_path 
)

write a Conduit Blueprint index to an existing root file

Given a domain that adheres to Conduit's Blueprint format, this method generates a Blueprint index and writes it to an existing root file.

The domain must be stored in a Group located at the path in the DataStore specified by domain_path argument.

This currently only works if the root file was created for protocol sidre_hdf5. This must be called after calling write().

The parameters domain_path and mesh_path are related. domain_path is the path from the root of the DataStore to the domain that is being used to generate the index. mesh_path is the path from the group that was passed into the preceding write() call to the same domain. If write() was called using the root group of the DataStore, then domain_path and mesh_path will be identical. Otherwise mesh_path is a sub-path of domain_path.

For example, the DataStore may contain a hierarchy of data that looks like this, and we want to generate a blueprint index based on the mesh located at "/hierarchy/domain_data/domain/blueprint_mesh":

<root> |–hierarchy | |–domain_data | |–domain | | |–blueprint_mesh | | |–coordsets | | | |–... | | |–topologies | | | |–... | | |–fields | | |–... | |–... |–

If write() is called using the Group located at "/hierarchy/domain_data", then only the Groups and Views descending from that Group are written to the file. To call this method, we would choose the full path in the DataStore "hierarchy/domain_data/domain/blueprint_mesh" for domain_path. For the mesh_path argument, we choose only the path that exists in the file: "domain/blueprint_mesh".

This is not an MPI collective call. One rank writes a blueprint index to one root file.

Parameters
datastoreDataStore containing Groups that hold domains that adhere to the Blueprint format
domain_pathpath in the DataStore to the domain that will be used to generate a Blueprint index
file_namename of existing root file
mesh_pathpath in the data file to the domain that will be used to generate a Blueprint index

◆ read() [1/2]

void axom::sidre::IOManager::read ( sidre::Group group,
const std::string &  root_file,
const std::string &  protocol,
bool  preserve_contents = false 
)

read from input file

This is an MPI collective call on all ranks in the communicator used to construct this object. Calling code may also need to add an MPI barrier after this call if invoking subsequent operations that may change the input files.

Parameters
groupGroup to fill with input data
root_fileroot file containing input data
protocolidentifies I/O protocol
preserve_contentsPreserves group's existing contents if true

◆ read() [2/2]

void axom::sidre::IOManager::read ( sidre::Group group,
const std::string &  root_file,
bool  preserve_contents = false 
)

read from a root file

This is an MPI collective call on all ranks in the communicator used to construct this object. Calling code may also need to add an MPI barrier after this call if invoking subsequent operations that may change the input files.

Parameters
groupGroup to fill with input data
root_fileroot file containing input data
preserve_contentsPreserves group's existing contents if true

◆ correspondingRelayProtocol()

static std::string axom::sidre::IOManager::correspondingRelayProtocol ( const std::string &  sidre_protocol)
static

Finds conduit relay protocol corresponding to a sidre protocol.

Parameters
sidre_protocolString representing the sidre protocol
Returns
The conduit relay protocol corresponding to sidre_protocol Options are: "hdf5", "json" and "conduit_json"
See also
Group::save() for a list of valid sidre protocols

◆ loadExternalData()

void axom::sidre::IOManager::loadExternalData ( sidre::Group group,
const std::string &  root_file 
)

load external data into a group

This currently only works if the root file was created for protocol sidre_hdf5.

Parameters
groupGroup to fill with external data from input
root_fileroot file containing input data

◆ getNumFilesFromRoot()

int axom::sidre::IOManager::getNumFilesFromRoot ( const std::string &  root_file)

gets the number of files in the dataset from the specified root file

◆ getNumGroupsFromRoot()

int axom::sidre::IOManager::getNumGroupsFromRoot ( const std::string &  root_file)

gets the number of groups in the dataset from the specified root file

Usually this is the number of MPI ranks that wrote data to this set of files.


The documentation for this class was generated from the following file: