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

com	MPI communicator
use_scr	Use 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

group	Group to write to output
num_files	number of output data files
file_base	base name for output files
protocol	identifies I/O protocol
tree_pattern	Optional 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

group	Group to add to root file
file_name	name 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

group	Group to add to root file
file_name	name of existing root file
group_path	path 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

view	View to add to root file
file_name	name of existing root file
group_path	path 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":

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

datastore	DataStore containing Groups that hold domains that adhere to the Blueprint format
domain_path	path in the DataStore to the domain that will be used to generate a Blueprint index
file_name	name of existing root file
mesh_path	path 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

group	Group to fill with input data
root_file	root file containing input data
protocol	identifies I/O protocol
preserve_contents	Preserves 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

group	Group to fill with input data
root_file	root file containing input data
preserve_contents	Preserves 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_protocol String 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

group	Group to fill with external data from input
root_file	root 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:

/home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/develop/src/axom/sidre/spio/IOManager.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ IOManager()

◆ ~IOManager()

Member Function Documentation

◆ write()

◆ writeGroupToRootFile()

◆ writeGroupToRootFileAtPath()

◆ writeViewToRootFileAtPath()

◆ writeBlueprintIndexToRootFile()

◆ read() [1/2]

◆ read() [2/2]

◆ correspondingRelayProtocol()

◆ loadExternalData()

◆ getNumFilesFromRoot()

◆ getNumGroupsFromRoot()