openswmm::h5io Namespace Reference

Classes
class	Handle
	Owns an hid_t and closes it with the right H5*close on scope exit. More...
class	Hdf5InputPlugin
class	Hdf5PluginInfo
	Singleton describing the HDF5 I/O plugin. More...

Functions
int	write_model (const std::string &path, const SimulationContext &ctx, std::vector< std::string > *warnings=nullptr)
	Write a complete native model and analysis columns to HDF5.
Handle	open_file_readonly (const std::string &path)
	Open an existing HDF5 file for read-only access.
std::string	column_units (hid_t group, const std::string &column)
	A column's units attribute, or "" when it has none.
Handle	make_string_type ()
	A variable-length UTF-8 string type, for name columns.
Handle	make_group (hid_t loc, const std::string &name)
	Create (or open) a group, creating intermediate groups as needed.
Handle	open_group (hid_t loc, const std::string &name)
	Open an existing HDF5 group.
bool	has_link (hid_t loc, const std::string &name)
	True when loc contains name.
bool	write_attr (hid_t loc, const std::string &name, const std::string &value)
	Create or replace a scalar std::string attribute.
bool	write_attr (hid_t loc, const std::string &name, double value)
	Create or replace a scalar double attribute.
bool	write_attr (hid_t loc, const std::string &name, int value)
	Create or replace a scalar int attribute.
bool	read_attr (hid_t loc, const std::string &name, std::string &out)
	Read a scalar attribute as std::string.
bool	read_attr (hid_t loc, const std::string &name, double &out)
	Read a scalar attribute as double.
bool	read_attr (hid_t loc, const std::string &name, int &out)
	Read a scalar attribute as int.
bool	write_column (hid_t group, const std::string &name, const std::vector< double > &values, const std::string &units="", const std::string &description="", int compression=4)
	Create a one-dimensional double column with optional metadata.
bool	write_column (hid_t group, const std::string &name, const std::vector< int > &values, const std::string &units="", const std::string &description="", int compression=4)
	Create a one-dimensional int column with optional metadata.
bool	write_column (hid_t group, const std::string &name, const std::vector< std::string > &values, const std::string &description="", int compression=4)
	Create a one-dimensional std::string column with optional metadata.
bool	read_column (hid_t group, const std::string &name, std::vector< double > &out)
	Read a one-dimensional column into a double vector.
bool	read_column (hid_t group, const std::string &name, std::vector< int > &out)
	Read a one-dimensional column into a int vector.
bool	read_column (hid_t group, const std::string &name, std::vector< std::string > &out)
	Read a one-dimensional column into a std::string vector.
std::size_t	column_length (hid_t group, const std::string &probe)
	Row count of a group's columns — the length of probe, or 0 if absent.

Variables
constexpr int	kSchemaVersionMajor = 1
constexpr int	kSchemaVersionMinor = 0
constexpr const char *	kSchemaVersion = "1.0"

Function Documentation

column_length()

std::size_t openswmm::h5io::column_length	(	hid_t	group,
		const std::string &	probe )

Row count of a group's columns — the length of probe, or 0 if absent.

Inspect the number of rows in a one-dimensional probe column.

Parameters

[in]	group	Borrowed source group from this HDF5 instance.
[in]	probe	Dataset name relative to group.

Returns

Row count; zero for an empty, missing or unopenable dataset, or a dataspace-query failure.

Precondition

An existing probe dataset has rank one; rank is not validated here.

Here is the call graph for this function:

column_units()

std::string openswmm::h5io::column_units	(	hid_t	group,
		const std::string &	column )

A column's units attribute, or "" when it has none.

Read a dataset's units attribute.

Parameters

[in]	group	Borrowed file/group identifier from this HDF5 instance.
[in]	column	Dataset name relative to group.

Returns

Owned units string, or an empty string if the link, dataset or attribute cannot be read. An explicitly empty units value also returns empty.

Here is the call graph for this function:

has_link()

bool openswmm::h5io::has_link	(	hid_t	loc,
		const std::string &	name )

True when loc contains name.

Test a path's links while checking each nonempty ancestor component.

Parameters

[in]	loc	Borrowed file/group identifier from this HDF5 instance.
[in]	name	Link path; empty components and leading slashes are skipped.

Returns

True when every nonempty accumulated component exists; false for an empty path, a missing ancestor or an HDF5 lookup error.

Note

Existence does not imply that the target is a group or dataset.

Here is the caller graph for this function:

make_group()

Handle openswmm::h5io::make_group	(	hid_t	loc,
		const std::string &	name )

Create (or open) a group, creating intermediate groups as needed.

Open a group or create it with any missing parent groups.

Parameters

[in]	loc	Borrowed file/group identifier from this HDF5 instance.
[in]	name	Group path relative to loc; must denote a group if it exists.

Returns

Owned group handle, or an empty handle on open/create failure.

Note

Existing group contents are preserved.

Here is the call graph for this function:

make_string_type()

Handle openswmm::h5io::make_string_type

(

)

A variable-length UTF-8 string type, for name columns.

Allocate a variable-length UTF-8 HDF5 string datatype.

Returns

Owned datatype handle, or an empty handle if H5Tcopy fails.

Note

Subsequent string-size/character-set configuration errors are not checked separately. All HDF5 calls use the engine's library instance.

Here is the call graph for this function:

Here is the caller graph for this function:

open_file_readonly()

Handle openswmm::h5io::open_file_readonly

(

const std::string &

path

)

Open an existing HDF5 file for read-only access.

Open an existing model file read-only. Callers use this rather than H5Fopen so that every HDF5 call stays inside the engine's instance.

Parameters

[in]

path

Borrowed filename passed to H5Fopen; must identify a readable file.

Returns

Owned file handle, or an empty handle on open failure.

open_group()

Handle openswmm::h5io::open_group	(	hid_t	loc,
		const std::string &	name )

Open an existing HDF5 group.

Parameters

[in]	loc	Borrowed file/group identifier from this HDF5 instance.
[in]	name	Group path relative to loc.

Returns

Owned group handle, or an empty handle on failure. No groups are created.

Here is the caller graph for this function:

read_attr() [1/3]

bool openswmm::h5io::read_attr	(	hid_t	loc,
		const std::string &	name,
		double &	out )

Read a scalar attribute as double.

Parameters

[in]	loc	Borrowed object or file identifier; a file targets its root group.
[in]	name	Attribute name to find.
[out]	out	Caller-owned value assigned on success. On HDF5 read failure its value is unspecified; a missing attribute leaves it unchanged.

Returns

True after a successful read; false for missing attributes or HDF5 errors.

Note

Numeric conversion follows HDF5 rules; string storage is copied and any variable-length HDF5 allocation is reclaimed by the helper.

Here is the call graph for this function:

read_attr() [2/3]

bool openswmm::h5io::read_attr	(	hid_t	loc,
		const std::string &	name,
		int &	out )

Read a scalar attribute as int.

Parameters

[in]	loc	Borrowed object or file identifier; a file targets its root group.
[in]	name	Attribute name to find.
[out]	out	Caller-owned value assigned on success. On HDF5 read failure its value is unspecified; a missing attribute leaves it unchanged.

Returns

True after a successful read; false for missing attributes or HDF5 errors.

Note

Numeric conversion follows HDF5 rules; string storage is copied and any variable-length HDF5 allocation is reclaimed by the helper.

Here is the call graph for this function:

read_attr() [3/3]

bool openswmm::h5io::read_attr	(	hid_t	loc,
		const std::string &	name,
		std::string &	out )

Read a scalar attribute as std::string.

Parameters

[in]	loc	Borrowed object or file identifier; a file targets its root group.
[in]	name	Attribute name to find.
[out]	out	Caller-owned value assigned on success. On HDF5 read failure its value is unspecified; a missing attribute leaves it unchanged.

Returns

True after a successful read; false for missing attributes or HDF5 errors.

Note

Numeric conversion follows HDF5 rules; string storage is copied and any variable-length HDF5 allocation is reclaimed by the helper.

Here is the call graph for this function:

Here is the caller graph for this function:

read_column() [1/3]

bool openswmm::h5io::read_column	(	hid_t	group,
		const std::string &	name,
		std::vector< double > &	out )

Read a one-dimensional column into a double vector.

Parameters

[in]	group	Borrowed source group from this HDF5 instance.
[in]	name	Existing dataset name relative to group.
[out]	out	Caller-owned vector resized to the stored length and filled on success. Missing/open failures leave it unchanged; later failures may leave it resized or partly filled.

Returns

True after a successful read, including an empty column; false for a missing link, failed open or failed data read.

Precondition

The dataset has rank one; shape/type validation is not performed here.

Note

Numeric conversion follows HDF5 rules. String data is copied before HDF5's temporary variable-length storage is reclaimed.

Here is the call graph for this function:

Here is the caller graph for this function:

read_column() [2/3]

bool openswmm::h5io::read_column	(	hid_t	group,
		const std::string &	name,
		std::vector< int > &	out )

Read a one-dimensional column into a int vector.

Parameters

[in]	group	Borrowed source group from this HDF5 instance.
[in]	name	Existing dataset name relative to group.
[out]	out	Caller-owned vector resized to the stored length and filled on success. Missing/open failures leave it unchanged; later failures may leave it resized or partly filled.

Returns

True after a successful read, including an empty column; false for a missing link, failed open or failed data read.

Precondition

The dataset has rank one; shape/type validation is not performed here.

Note

Numeric conversion follows HDF5 rules. String data is copied before HDF5's temporary variable-length storage is reclaimed.

Here is the call graph for this function:

read_column() [3/3]

bool openswmm::h5io::read_column	(	hid_t	group,
		const std::string &	name,
		std::vector< std::string > &	out )

Read a one-dimensional column into a std::string vector.

Parameters

[in]	group	Borrowed source group from this HDF5 instance.
[in]	name	Existing dataset name relative to group.
[out]	out	Caller-owned vector resized to the stored length and filled on success. Missing/open failures leave it unchanged; later failures may leave it resized or partly filled.

Returns

True after a successful read, including an empty column; false for a missing link, failed open or failed data read.

Precondition

The dataset has rank one; shape/type validation is not performed here.

Note

Numeric conversion follows HDF5 rules. String data is copied before HDF5's temporary variable-length storage is reclaimed.

Here is the call graph for this function:

write_attr() [1/3]

bool openswmm::h5io::write_attr	(	hid_t	loc,
		const std::string &	name,
		const std::string &	value )

Create or replace a scalar std::string attribute.

Parameters

[in]	loc	Borrowed object or file identifier; a file targets its root group.
[in]	name	Attribute name, borrowed for this call.
[in]	value	Value to store; numeric units are caller-defined.

Returns

True if the attribute was created and written; false on failure.

Note

An existing attribute is deleted before replacement, so failure may leave it absent. No rollback is performed and no inputs are retained.

Here is the call graph for this function:

write_attr() [2/3]

bool openswmm::h5io::write_attr	(	hid_t	loc,
		const std::string &	name,
		double	value )

Create or replace a scalar double attribute.

Parameters

[in]	loc	Borrowed object or file identifier; a file targets its root group.
[in]	name	Attribute name, borrowed for this call.
[in]	value	Value to store; numeric units are caller-defined.

Returns

True if the attribute was created and written; false on failure.

Note

An existing attribute is deleted before replacement, so failure may leave it absent. No rollback is performed and no inputs are retained.

Here is the call graph for this function:

write_attr() [3/3]

bool openswmm::h5io::write_attr	(	hid_t	loc,
		const std::string &	name,
		int	value )

Create or replace a scalar int attribute.

Parameters

[in]	loc	Borrowed object or file identifier; a file targets its root group.
[in]	name	Attribute name, borrowed for this call.
[in]	value	Value to store; numeric units are caller-defined.

Returns

True if the attribute was created and written; false on failure.

Note

An existing attribute is deleted before replacement, so failure may leave it absent. No rollback is performed and no inputs are retained.

Here is the call graph for this function:

write_column() [1/3]

bool openswmm::h5io::write_column	(	hid_t	group,
		const std::string &	name,
		const std::vector< double > &	values,
		const std::string &	units = "",
		const std::string &	description = "",
		int	compression = 4 )

Create a one-dimensional double column with optional metadata.

Parameters

[in]	group	Borrowed destination group from this HDF5 instance.
[in]	name	New dataset name; an existing link is not replaced.
[in]	values	Borrowed column data; empty creates an explicit zero-length dataset.
[in]	units	Optional units attribute; empty omits it.
[in]	description	Optional description attribute; empty omits it.
[in]	compression	Deflate level 1..9; <= 0 disables compression. Empty columns are uncompressed; positive levels request chunks of up to 1024 rows.

Returns

True when dataset creation and the data write succeed; false otherwise. Metadata and property-configuration errors are not reflected separately.

Note

Values are copied synchronously and no inputs are retained. Failure may leave a dataset or metadata behind; this helper does not roll back.

Here is the call graph for this function:

write_column() [2/3]

bool openswmm::h5io::write_column	(	hid_t	group,
		const std::string &	name,
		const std::vector< int > &	values,
		const std::string &	units = "",
		const std::string &	description = "",
		int	compression = 4 )

Create a one-dimensional int column with optional metadata.

Parameters

[in]	group	Borrowed destination group from this HDF5 instance.
[in]	name	New dataset name; an existing link is not replaced.
[in]	values	Borrowed column data; empty creates an explicit zero-length dataset.
[in]	units	Optional units attribute; empty omits it.
[in]	description	Optional description attribute; empty omits it.
[in]	compression	Deflate level 1..9; <= 0 disables compression. Empty columns are uncompressed; positive levels request chunks of up to 1024 rows.

Returns

True when dataset creation and the data write succeed; false otherwise. Metadata and property-configuration errors are not reflected separately.

Note

Values are copied synchronously and no inputs are retained. Failure may leave a dataset or metadata behind; this helper does not roll back.

Here is the call graph for this function:

write_column() [3/3]

bool openswmm::h5io::write_column	(	hid_t	group,
		const std::string &	name,
		const std::vector< std::string > &	values,
		const std::string &	description = "",
		int	compression = 4 )

Create a one-dimensional std::string column with optional metadata.

Parameters

[in]	group	Borrowed destination group from this HDF5 instance.
[in]	name	New dataset name; an existing link is not replaced.
[in]	values	Borrowed column data; empty creates an explicit zero-length dataset.
[in]	description	Optional description attribute; empty omits it.
[in]	compression	Deflate level 1..9; <= 0 disables compression. Empty columns are uncompressed; positive levels request chunks of up to 1024 rows.

Returns

True when dataset creation and the data write succeed; false otherwise. Metadata and property-configuration errors are not reflected separately.

Note

Values are copied synchronously and no inputs are retained. Failure may leave a dataset or metadata behind; this helper does not roll back.

Here is the call graph for this function:

write_model()

int openswmm::h5io::write_model	(	const std::string &	path,
		const SimulationContext &	ctx,
		std::vector< std::string > *	warnings = nullptr )

Write a complete native model and analysis columns to HDF5.

Parameters

path	Destination filename, created or truncated.
ctx	Model in engine internal units; not modified.
warnings	Optional diagnostics sink, preserved and appended to.

Returns

Zero after writing and flushing; nonzero on I/O failure. The native_input dataset is the authoritative editable configuration. Existing column datasets retain their authored-unit analysis layout. Component configuration contents are embedded separately. Older column-only files lack enough data to reopen. Conversion/allocation exceptions propagate. Failure may leave a partial destination.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

kSchemaVersion

const char* openswmm::h5io::kSchemaVersion = "1.0"

inlineconstexpr

kSchemaVersionMajor

int openswmm::h5io::kSchemaVersionMajor = 1

inlineconstexpr

Bumped on any layout change. The reader refuses a major it does not know rather than silently misreading a file written by a newer engine.

kSchemaVersionMinor

int openswmm::h5io::kSchemaVersionMinor = 0

inlineconstexpr