Namespaces
	internal

Classes
class	Curve

class	CurveSet
	A CurveSet represents an entry in a record's "curve_set". More...

class	DataHolder
	A DataHolder is a basic container for certain types of information. More...

class	Datum
	An object to track a value associated with a Record. More...

class	Document
	An object representing the top-level object of a Sina file. More...

class	File
	An object to help track locations of files in the file system. More...

class	ID
	The ID of a Record. More...

struct	FileEqualByURI

struct	FileHashByURI

class	Record
	An object representing an entry in a Document's Record list. More...

class	RecordLoader
	An object to convert Conduit Nodes into Records. More...

class	Relationship
	An object used to correlate 2 Records. More...

class	Run
	A sub-type of Record representing a single run of an applicaiton. More...

Enumerations
enum class	ValueType { String , Scalar , StringArray , ScalarArray }

enum class	Protocol { AUTO_DETECT = -1 , JSON = 0 , HDF5 = 1 }
	File format enum for explicit format specification. More...

enum class	IDType { Local , Global }

Functions
conduit::Node const &	getRequiredField (std::string const &fieldName, conduit::Node const &parent, std::string const &parentType)
	Get a required field from a conduit Node. More...

std::string	getRequiredString (std::string const &fieldName, conduit::Node const &parent, std::string const &parentType)
	Get the value of a required field from a conduit Node. The field value must be a string. More...

double	getRequiredDouble (std::string const &fieldName, conduit::Node const &parent, std::string const &parentType)
	Get the value of a required field from a conduit Node. The field value must be a double. More...

std::string	getOptionalString (std::string const &fieldName, conduit::Node const &parent, std::string const &parentType)
	Get the value of an optional field from a conduit Node. The field value must be a string if it is present. More...

std::vector< double >	toDoubleVector (conduit::Node const &node, std::string const &name)
	Convert the given node to a vector of doubles. More...

std::vector< std::string >	toStringVector (conduit::Node const &node, std::string const &name)
	Convert the given node to a vector of strings. More...

void	addStringsToNode (conduit::Node &parent, const std::string &child_name, std::vector< std::string > const &string_values)
	Add a vector of strings to a Node. This operation's not natively part of Conduit. More...

void	setDefaultCurveOrder (CurveSet::CurveOrder order)
	Set the default curve order for all CurveSets. More...

void	saveDocument (Document const &document, std::string const &fileName, Protocol protocol=Protocol::AUTO_DETECT)
	Save the given Document to the specified location. If the given file exists, it will be overwritten. More...

std::string	getSinaFileFormatVersion ()
	Get the current file format version. More...

void	restoreSlashes (const conduit::Node &modifiedNode, conduit::Node &restoredNode)

Document	loadDocument (std::string const &path, Protocol protocol=Protocol::JSON)
	Load a document from the given path. Only records which this library knows about will be able to be loaded. More...

Document	loadDocument (std::string const &path, RecordLoader const &recordLoader, Protocol protocol=Protocol::JSON)
	Load a document from the given path. More...

conduit::Node	appendDocumentToJson (const std::string &jsonFilePath, const Document &newData, const int mergeProtocol=1, const bool skipValidation=false)
	Append the new records or, per-record, new data, user defined content, curves/curve sets, and library data of a Sina Document to an existing JSON file. For a full explanation of behavior, see appendDocumentToHDF5. Note that a JSON file must be entirely re-written for an append to function; it's more efficient for shorter files, but prefer HDF5 for large files (many timeseries/long timeseries) More...

conduit::Node	appendDocumentToHDF5 (const std::string &hdf5FilePath, Document const &newData, const int mergeProtocol=1, const bool skipValidation=false)
	Append the new records or, per-record, new data, user defined content, curves/curve sets, and library data of a Sina Document to an existing HDF5 file. Appending is meant to allow a Sina document to grow as a simulation continues, i.e. by appending new snapshots into the same file, or by writing additional points of a timeseries to disk as they become available. HDF5 is the preferred filetype for heavy appending into, as it does not require being entirely re-written to file each time, unlike JSON. More...

void	appendDocument (const Document &document, const std::string &filepath, int mergeProtocol=1, Protocol Protocol=Protocol::AUTO_DETECT)
	Append a Document to an existing file with automatic format detection. More...

template<typename ConduitRelayLike >
conduit::Node	validateAppendDocument (ConduitRelayLike &appendTo, const conduit::Node &appendFrom, const std::string &endpoint, const int mergeProtocol, int record_num, const std::string &original_file_path="")
	Check a node against some file handle and return a Conduit node populated with any errors that would prevent appending. Primarily useful for dry run testing of what may be going wrong with an append. More...

RecordLoader	createRecordLoaderWithAllKnownTypes ()
	Create a RecordLoader which can load records of all known types. More...

void	addRunLoader (RecordLoader &loader)
	Add a type loader to the given RecordLoader for loading Run instances. More...

Variables
CurveSet::CurveOrder	sinaDefaultCurveOrder

const std::vector< std::string >	supported_types

const std::string	slashSubstitute = "__SINA_SLASHREPLACE__"
	The string used to replace '/' in parent node names when saving to HDF5. More...

Enumeration Type Documentation

◆ ValueType

enum axom::sina::ValueType

strong

Represents whether a Datum is a String, Scalar (double), array of Strings, or array of Scalars.

Enumerator
String
Scalar
StringArray
ScalarArray

◆ Protocol

enum axom::sina::Protocol

strong

File format enum for explicit format specification.

This enum provides type-safe format specification for saveDocument and appendDocument functions. It works alongside the existing supported_types for backward compatibility.

The enum values map to supported_types indices:

AUTO_DETECT: Special value for auto-detection from file extension
JSON: maps to supported_types[0] = "JSON"
HDF5: maps to supported_types[1] = "HDF5" (if AXOM_USE_HDF5 is defined)

Enumerator
AUTO_DETECT	Automatically detect from file extension (.json, .h5, .hdf5)
JSON	Force JSON format (supported_types[0])
HDF5	Force HDF5 format (supported_types[1], requires AXOM_USE_HDF5)

◆ IDType

enum axom::sina::IDType

strong

Represents whether an ID is local or global.

Enumerator
Local
Global

Function Documentation

◆ getRequiredField()

conduit::Node const& axom::sina::getRequiredField	(	std::string const &	fieldName,
		conduit::Node const &	parent,
		std::string const &	parentType
	)

Get a required field from a conduit Node.

Parameters

fieldName	the name of the field to get
parent	the parent object from which to get the field
parentType	a user-friendly name of the type of the parent to use in an error message if the field doesn't exist.

Returns: the requested field as a Node

Exceptions

std::invalid_argument if the field does not exist

◆ getRequiredString()

std::string axom::sina::getRequiredString	(	std::string const &	fieldName,
		conduit::Node const &	parent,
		std::string const &	parentType
	)

Get the value of a required field from a conduit Node. The field value must be a string.

Parameters

fieldName	the name of the field to get
parent	the parent object from which to get the field
parentType	a user-friendly name of the type of the parent to use in an error message if the field doesn't exist.

Returns: the value of the requested field

Exceptions

std::invalid_argument if the field does not exist or is not a string

◆ getRequiredDouble()

double axom::sina::getRequiredDouble	(	std::string const &	fieldName,
		conduit::Node const &	parent,
		std::string const &	parentType
	)

Get the value of a required field from a conduit Node. The field value must be a double.

Parameters

fieldName	the name of the field to get
parent	the parent object from which to get the field
parentType	a user-friendly name of the type of the parent to use in an error message if the field doesn't exist.

Returns: the value of the requested field

Exceptions

std::invalid_argument if the field does not exist or is not a double

◆ getOptionalString()

std::string axom::sina::getOptionalString	(	std::string const &	fieldName,
		conduit::Node const &	parent,
		std::string const &	parentType
	)

Get the value of an optional field from a conduit Node. The field value must be a string if it is present.

Parameters

fieldName	the name of the field to get
parent	the parent object from which to get the field
parentType	a user-friendly name of the type of the parent to use in an error message if the field doesn't exist.

Returns: the value of the requested field, or an empty string if it does not exist

Exceptions

std::invalid_argument if the field exists but is not a string

◆ toDoubleVector()

std::vector<double> axom::sina::toDoubleVector	(	conduit::Node const &	node,
		std::string const &	name
	)

Convert the given node to a vector of doubles.

Parameters

node	the node to convert
name	the name of the node, used in error reporting

Returns: the node as a list of doubles

Exceptions

std::invalid_argument if the node is not a list of doubles

◆ toStringVector()

std::vector<std::string> axom::sina::toStringVector	(	conduit::Node const &	node,
		std::string const &	name
	)

Convert the given node to a vector of strings.

Parameters

node	the node to convert
name	the name of the node, used in error reporting

Returns: the node as a list of strings

Exceptions

std::invalid_argument if the node is not a list of strings

◆ addStringsToNode()

void axom::sina::addStringsToNode	(	conduit::Node &	parent,
		const std::string &	child_name,
		std::vector< std::string > const &	string_values
	)

Add a vector of strings to a Node. This operation's not natively part of Conduit.

Parameters

parent	the node to add the strings to
child_name	the name of the child (aka the name of the field)
string_values	the data values for the field

◆ setDefaultCurveOrder()

void axom::sina::setDefaultCurveOrder ( CurveSet::CurveOrder order )

Set the default curve order for all CurveSets.

Parameters

order The curve order to use as the default

◆ saveDocument()

void axom::sina::saveDocument	(	Document const &	document,
		std::string const &	fileName,
		Protocol	protocol = `Protocol::AUTO_DETECT`
	)

Save the given Document to the specified location. If the given file exists, it will be overwritten.

Parameters

document	the Document to save
fileName	the location of which to save the file
protocol	the file type requested to save as contained in supported_types, default = JSON

Exceptions

std::ios::failure if there are any IO errors std::invalid_argument if the protocol given is an undefined, optional protocol

◆ getSinaFileFormatVersion()

std::string axom::sina::getSinaFileFormatVersion ( )

inline

Get the current file format version.

Returns: A string representing the file format version.

References SINA_FILE_FORMAT_VERSION_MAJOR, and SINA_FILE_FORMAT_VERSION_MINOR.

◆ restoreSlashes()

void axom::sina::restoreSlashes	(	const conduit::Node &	modifiedNode,
		conduit::Node &	restoredNode
	)

◆ loadDocument() [1/2]

Document axom::sina::loadDocument	(	std::string const &	path,
		Protocol	protocol = `Protocol::JSON`
	)

Load a document from the given path. Only records which this library knows about will be able to be loaded.

Parameters

path	the file system path from which to load the document
protocol	the type of file being loaded, default = JSON

Returns: the loaded Document

◆ loadDocument() [2/2]

Document axom::sina::loadDocument	(	std::string const &	path,
		RecordLoader const &	recordLoader,
		Protocol	protocol = `Protocol::JSON`
	)

Load a document from the given path.

Parameters

path	the file system path from which to load the document
recordLoader	the RecordLoader to use to load the different types of records
protocol	the type of file being loaded, default = JSON

Exceptions

std::invalid_argument if the protocol given is an undefined, optional protocol

Returns: the loaded Document

◆ appendDocumentToJson()

conduit::Node axom::sina::appendDocumentToJson	(	const std::string &	jsonFilePath,
		const Document &	newData,
		const int	mergeProtocol = `1`,
		const bool	skipValidation = `false`
	)

Append the new records or, per-record, new data, user defined content, curves/curve sets, and library data of a Sina Document to an existing JSON file. For a full explanation of behavior, see appendDocumentToHDF5. Note that a JSON file must be entirely re-written for an append to function; it's more efficient for shorter files, but prefer HDF5 for large files (many timeseries/long timeseries)

Parameters

jsonFilePath	the path to the JSON file
newData	a Sina Document containing the new data to append
mergeProtocol	protocol for handling duplicate data/files/user_defined/etc 1 = take the new value. 2 = keep the old value. 3/Other = Cancel the append. Protocol 1 is the conduit default behavior. Ignored entirely when skipping validation.
skipValidation	whether to skip the validation step entirely. Most useful for well-controlled cases, ex: a code is appending values to every timeseries every N cycles.

Returns: a conduit Node containing a list of any errors encountered in appending. If empty, success.

◆ appendDocumentToHDF5()

conduit::Node axom::sina::appendDocumentToHDF5	(	const std::string &	hdf5FilePath,
		Document const &	newData,
		const int	mergeProtocol = `1`,
		const bool	skipValidation = `false`
	)

Append the new records or, per-record, new data, user defined content, curves/curve sets, and library data of a Sina Document to an existing HDF5 file. Appending is meant to allow a Sina document to grow as a simulation continues, i.e. by appending new snapshots into the same file, or by writing additional points of a timeseries to disk as they become available. HDF5 is the preferred filetype for heavy appending into, as it does not require being entirely re-written to file each time, unlike JSON.

When appending a new Document to one already written on disk, it will first find any records that don't exist in the file on disk and add them. Then, for any file it finds that does exist, it will go through its various fields and compare them. New data/curve sets/etc. will simply be added in. For fields that already exist:

For curves in curve sets, new values will be appended onto the end. This is useful for ex: codes that don't store curves in memory, appending the new set of curve values each cycle will allow the file on disk to grow as the simulation continues.

For everything else (data, files, user_defined...), behavior depends on mergeProtocol, with the default behavior being to overwrite the old (on-disk) field with the new value.

Parameters

hdf5FilePath	the path to the HDF5 file
new_data	a vector of the new data to append
mergeProtocol	protocol for handling duplicate data/files/user_defined/etc 1 = take the new value. 2 = keep the old value. 3 = Cancel the append. Protocol 1 is the conduit default behavior. Ignored entirely when skipping validation.
skipValidation	whether to skip the validation step entirely. Most useful for well-controlled cases, ex: a code is appending values to every timeseries every N cycles.

Returns: a conduit Node containing a list of any errors encountered in appending. If empty, success!

◆ appendDocument()

void axom::sina::appendDocument	(	const Document &	document,
		const std::string &	filepath,
		int	mergeProtocol = `1`,
		Protocol	Protocol = `Protocol::AUTO_DETECT`
	)

Append a Document to an existing file with automatic format detection.

Automatically detects the file format from the extension and appends accordingly. The format can optionally be overridden.

Parameters

document	The Document to append
filepath	Path to the existing file
mergeProtocol	How to handle conflicts (1=KEEP_ORIGINAL, 2=OVERWRITE, 3=ERROR)
outputProtocol	Optional format override (default: AUTO_DETECT)

Exceptions

std::runtime_error If the file cannot be opened or the format is unsupported

◆ validateAppendDocument()

template<typename ConduitRelayLike >

conduit::Node axom::sina::validateAppendDocument	(	ConduitRelayLike &	appendTo,
		const conduit::Node &	appendFrom,
		const std::string &	endpoint,
		const int	mergeProtocol,
		int	record_num,
		const std::string &	original_file_path = `""`
	)

Check a node against some file handle and return a Conduit node populated with any errors that would prevent appending. Primarily useful for dry run testing of what may be going wrong with an append.

Parameters

appendTo	Either a conduit node or a conduit relay filehandle (prefer the latter for HDF5) representing the data on disk
appendFrom	A conduit node representing the document being appended to the file on disk
endpoint	The endpoint within the record at which the node should be checked. This is primarily useful for library_data
mergeProtocol	protocol for handling duplicate data/files/user_defined/etc. See append methods above.
record_num	The offset of the record within appendFrom, i.e. if you'd like to test the append against the first record, pass 0
original_file_path	The path to the appendFrom document on disk, required for fast lookup of some HDF5 info

Returns: a conduit Node containing a list of any errors encountered in appending. If empty, success.

◆ createRecordLoaderWithAllKnownTypes()

RecordLoader axom::sina::createRecordLoaderWithAllKnownTypes ( )

Create a RecordLoader which can load records of all known types.

Returns: the newly-created loader

◆ addRunLoader()

void axom::sina::addRunLoader ( RecordLoader & loader )

Add a type loader to the given RecordLoader for loading Run instances.

Parameters

loader the RecordLoader to which to add the function for loading Run instances.

Variable Documentation

◆ sinaDefaultCurveOrder

CurveSet::CurveOrder axom::sina::sinaDefaultCurveOrder

extern

◆ supported_types

const std::vector<std::string> axom::sina::supported_types

Initial value:

= {"JSON",
 
}

◆ slashSubstitute

const std::string axom::sina::slashSubstitute = "__SINA_SLASHREPLACE__"

The string used to replace '/' in parent node names when saving to HDF5.

Namespaces

Classes

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ ValueType

◆ Protocol

◆ IDType

Function Documentation

◆ getRequiredField()

◆ getRequiredString()

◆ getRequiredDouble()

◆ getOptionalString()

◆ toDoubleVector()

◆ toStringVector()

◆ addStringsToNode()

◆ setDefaultCurveOrder()

◆ saveDocument()

◆ getSinaFileFormatVersion()

◆ restoreSlashes()

◆ loadDocument() [1/2]

◆ loadDocument() [2/2]

◆ appendDocumentToJson()

◆ appendDocumentToHDF5()

◆ appendDocument()

◆ validateAppendDocument()

◆ createRecordLoaderWithAllKnownTypes()

◆ addRunLoader()

Variable Documentation

◆ sinaDefaultCurveOrder

◆ supported_types

◆ slashSubstitute