A container class holding arrays of state information. More...

#include <SolutionArray.h>

Detailed Description

A container class holding arrays of state information.

SolutionArray objects provide a convenient interface for representing many thermodynamic states using the same Solution object. C++ SolutionArray objects are one-dimensional by design; while shape information for multi-dimensional arrays is stored, reshaping operations need to be implemented in high-level API's.

The SolutionArray class implements the main interface for saving and restoring of Cantera simulation data. SolutionArray objects can be serialized to and from YAML and HDF container files using the save() and restore() methods. In addition, there is limited support for CSV files.

Since: New in Cantera 3.0.

Definition at line 32 of file SolutionArray.h.

Public Member Functions
shared_ptr< SolutionArray >	share (const vector< int > &selected)
	Share locations from an existing SolutionArray and return new reference.

void	reset ()
	Reset all entries of the SolutionArray to the current Solution state.

int	size () const
	Size of SolutionArray (number of entries).

void	resize (int size)
	Resize SolutionArray objects with a single dimension (default).

vector< long int >	apiShape () const
	SolutionArray shape information used by high-level API's.

void	setApiShape (const vector< long int > &shape)
	Set SolutionArray shape information used by high-level API's.

int	apiNdim () const
	Number of SolutionArray dimensions used by high-level API's.

string	info (const vector< string > &keys, int rows=10, int width=80)
	Print a concise summary of a SolutionArray.

AnyMap &	meta ()
	SolutionArray meta data.

void	setMeta (const AnyMap &meta)
	Set SolutionArray meta data.

shared_ptr< Solution >	solution ()
	Retrieve associated Solution object.

shared_ptr< ThermoPhase >	thermo ()
	Retrieve associated ThermoPhase object.

vector< string >	componentNames () const
	Retrieve list of component names.

bool	hasComponent (const string &name) const
	Check whether SolutionArray contains a component.

AnyValue	getComponent (const string &name) const
	Retrieve a component of the SolutionArray by name.

void	setComponent (const string &name, const AnyValue &data)
	Set a component of the SolutionArray by name.

void	setLoc (int loc, bool restore=true)
	Update the buffered location used to access SolutionArray entries.

void	updateState (int loc)
	Update state at given location to state of associated Solution object.

vector< double >	getState (int loc)
	Retrieve the state vector for a given location.

void	setState (int loc, const vector< double > &state)
	Set the state vector for a given location.

void	normalize ()
	Normalize mass/mole fractions.

void	addExtra (const string &name, bool back=true)
	Add auxiliary component to SolutionArray.

bool	hasExtra (const string &name) const
	Check whether SolutionArray contains an extra component.

vector< string >	listExtra (bool all=true) const
	Retrieve list of extra component names.

AnyMap	getAuxiliary (int loc)
	Retrieve auxiliary data for a given location.

void	setAuxiliary (int loc, const AnyMap &data)
	Set auxiliary data for a given location.

void	append (const vector< double > &state, const AnyMap &extra)
	Append location entry at end of SolutionArray.

void	writeEntry (const string &fname, bool overwrite=false, const string &basis="")
	Write SolutionArray data to a CSV file.

void	writeEntry (const string &fname, const string &name, const string &sub, bool overwrite=false, int compression=0)
	Write SolutionArray data to a HDF container file.

void	writeEntry (AnyMap &root, const string &name, const string &sub, bool overwrite=false)
	Write SolutionArray data to AnyMap.

void	save (const string &fname, const string &name="", const string &sub="", const string &desc="", bool overwrite=false, int compression=0, const string &basis="")
	Save current SolutionArray contents to a data file.

void	readEntry (const string &fname, const string &name, const string &sub)
	Restore SolutionArray data from a HDF container file.

void	readEntry (const AnyMap &root, const string &name, const string &sub)
	Restore SolutionArray data from AnyMap.

AnyMap	restore (const string &fname, const string &name, const string &sub="")
	Restore SolutionArray data and header information from a container file.

Static Public Member Functions
static shared_ptr< SolutionArray >	create (const shared_ptr< Solution > &sol, int size=0, const AnyMap &meta={})
	Instantiate a new SolutionArray reference.

static void	writeHeader (const string &fname, const string &name, const string &desc, bool overwrite=false)
	Write header data to a HDF container file.

static void	writeHeader (AnyMap &root, const string &name, const string &desc, bool overwrite=false)
	Write header data to AnyMap.

static AnyMap	readHeader (const string &fname, const string &name)
	Read header information from a HDF container file.

static AnyMap	readHeader (const AnyMap &root, const string &name)
	Read header information from AnyMap.

Protected Member Functions
void	_resize (size_t size)
	Service function used to resize SolutionArray.

void	_initExtra (const string &name, const AnyValue &value)
	Initialize extra SolutionArray component.

void	_resizeExtra (const string &name, const AnyValue &value=AnyValue())
	Resize extra SolutionArray component.

void	_setExtra (const string &name, const AnyValue &data=AnyValue())
	Set extra SolutionArray component.

string	_detectMode (const set< string > &names, bool native=true)
	Identify storage mode of state data.

set< string >	_stateProperties (const string &mode, bool alias=false)
	Retrieve set containing list of properties defining state.

Protected Attributes
shared_ptr< Solution >	m_sol
	Solution object associated with state data.

size_t	m_size
	Number of entries in SolutionArray.

size_t	m_dataSize
	Total size of unsliced data.

size_t	m_stride
	Stride between SolutionArray entries.

AnyMap	m_meta
	Metadata.

size_t	m_loc = npos
	Buffered location within data vector.

vector< long int >	m_apiShape
	Shape information used by high-level API's.

shared_ptr< vector< double > >	m_data
	Work vector holding states.

shared_ptr< map< string, AnyValue > >	m_extra
	Auxiliary (extra) components; size of first dimension has to match m_dataSize.

shared_ptr< map< int, string > >	m_order
	Mapping of auxiliary component names, where the index is used as the mapping key.

bool	m_shared = false
	`true` if data are shared from another object

vector< int >	m_active
	Vector of locations referencing active entries.

Private Member Functions
	SolutionArray (const shared_ptr< Solution > &sol, int size, const AnyMap &meta)

	SolutionArray (const SolutionArray &arr, const vector< int > &indices)

Constructor & Destructor Documentation

◆ SolutionArray() [1/2]

SolutionArray	(	const shared_ptr< Solution > &	sol,
		int	size,
		const AnyMap &	meta
	)

private

Definition at line 40 of file SolutionArray.cpp.

◆ SolutionArray() [2/2]

SolutionArray	(	const SolutionArray &	arr,
		const vector< int > &	indices
	)

private

Definition at line 63 of file SolutionArray.cpp.

◆ ~SolutionArray()

virtual ~SolutionArray ( )

inlinevirtual

Definition at line 42 of file SolutionArray.h.

Member Function Documentation

◆ create()

static shared_ptr< SolutionArray > create	(	const shared_ptr< Solution > &	sol,
		int	size = `0`,
		const AnyMap &	meta = `{}`
	)

inlinestatic

Instantiate a new SolutionArray reference.

Parameters

sol	Solution object defining phase definitions
size	Number of SolutionArray entries
meta	AnyMap holding SolutionArray meta data

Definition at line 51 of file SolutionArray.h.

◆ share()

shared_ptr< SolutionArray > share ( const vector< int > & selected )

inline

Share locations from an existing SolutionArray and return new reference.

Both SolutionArray object share common data. The method is used for slicing of SolutionArrays from high-level API's. Note that meta data are not inherited.

Parameters

selected List of locations for shared entries

Definition at line 65 of file SolutionArray.h.

◆ reset()

void reset ( )

Reset all entries of the SolutionArray to the current Solution state.

Definition at line 123 of file SolutionArray.cpp.

◆ size()

int size ( ) const

inline

Size of SolutionArray (number of entries).

Definition at line 74 of file SolutionArray.h.

◆ resize()

void resize ( int size )

Resize SolutionArray objects with a single dimension (default).

Definition at line 154 of file SolutionArray.cpp.

◆ apiShape()

vector< long int > apiShape ( ) const

inline

SolutionArray shape information used by high-level API's.

Definition at line 82 of file SolutionArray.h.

◆ setApiShape()

void setApiShape ( const vector< long int > & shape )

Set SolutionArray shape information used by high-level API's.

The size of the SolutionArray is adjusted automatically.

Definition at line 169 of file SolutionArray.cpp.

◆ apiNdim()

int apiNdim ( ) const

inline

Number of SolutionArray dimensions used by high-level API's.

Definition at line 91 of file SolutionArray.h.

◆ info()

string info	(	const vector< string > &	keys,
		int	rows = `10`,
		int	width = `80`
	)

Print a concise summary of a SolutionArray.

Parameters

keys	List of components to be displayed; if empty, all components are considered.
rows	Maximum number of rendered rows.
width	Maximum width of rendered output.

Definition at line 450 of file SolutionArray.cpp.

◆ meta()

AnyMap & meta ( )

inline

SolutionArray meta data.

Definition at line 105 of file SolutionArray.h.

◆ setMeta()

void setMeta ( const AnyMap & meta )

inline

Set SolutionArray meta data.

Definition at line 110 of file SolutionArray.h.

◆ solution()

shared_ptr< Solution > solution ( )

inline

Retrieve associated Solution object.

Definition at line 115 of file SolutionArray.h.

◆ thermo()

shared_ptr< ThermoPhase > thermo ( )

Retrieve associated ThermoPhase object.

Definition at line 534 of file SolutionArray.cpp.

◆ componentNames()

vector< string > componentNames ( ) const

Retrieve list of component names.

Definition at line 539 of file SolutionArray.cpp.

◆ hasComponent()

bool hasComponent ( const string & name ) const

Check whether SolutionArray contains a component.

A component is a property defining state or auxiliary variable.

Definition at line 622 of file SolutionArray.cpp.

◆ getComponent()

AnyValue getComponent ( const string & name ) const

Retrieve a component of the SolutionArray by name.

Returns an AnyValue containing an array with length size() with a type specific to the component; in most cases, the type is double, but may differ for auxiliary data.

Definition at line 640 of file SolutionArray.cpp.

◆ setComponent()

void setComponent	(	const string &	name,
		const AnyValue &	data
	)

Set a component of the SolutionArray by name.

The passed AnyValue should containing an array with length size() with a type specific to the component; in most cases, the type is double, but may differ for auxiliary data.

Parameters

name	Name of component (property defining auxiliary variable)
data	Component data

Definition at line 704 of file SolutionArray.cpp.

◆ setLoc()

void setLoc	(	int	loc,
		bool	restore = `true`
	)

Update the buffered location used to access SolutionArray entries.

Definition at line 739 of file SolutionArray.cpp.

◆ updateState()

void updateState ( int loc )

Update state at given location to state of associated Solution object.

Definition at line 763 of file SolutionArray.cpp.

◆ getState()

vector< double > getState ( int loc )

Retrieve the state vector for a given location.

Definition at line 770 of file SolutionArray.cpp.

◆ setState()

void setState	(	int	loc,
		const vector< double > &	state
	)

Set the state vector for a given location.

Definition at line 779 of file SolutionArray.cpp.

◆ normalize()

void normalize ( )

Normalize mass/mole fractions.

Definition at line 792 of file SolutionArray.cpp.

◆ addExtra()

void addExtra	(	const string &	name,
		bool	back = `true`
	)

Add auxiliary component to SolutionArray.

Initialization requires a subsequent call of setComponent().

Parameters

name	Name of component (property defining auxiliary variable)
back	If `true` (default), add name after components representing the state, otherwise add to front of list. Front and back components are populated left to right.

Definition at line 572 of file SolutionArray.cpp.

◆ hasExtra()

bool hasExtra ( const string & name ) const

inline

Check whether SolutionArray contains an extra component.

Definition at line 181 of file SolutionArray.h.

◆ listExtra()

vector< string > listExtra ( bool all = true ) const

Retrieve list of extra component names.

Definition at line 598 of file SolutionArray.cpp.

◆ getAuxiliary()

AnyMap getAuxiliary ( int loc )

Retrieve auxiliary data for a given location.

Definition at line 822 of file SolutionArray.cpp.

◆ setAuxiliary()

void setAuxiliary	(	int	loc,
		const AnyMap &	data
	)

Set auxiliary data for a given location.

Definition at line 850 of file SolutionArray.cpp.

◆ append()

void append	(	const vector< double > &	state,
		const AnyMap &	extra
	)

Append location entry at end of SolutionArray.

Definition at line 1258 of file SolutionArray.cpp.

◆ writeHeader() [1/2]

void writeHeader	(	const string &	fname,
		const string &	name,
		const string &	desc,
		bool	overwrite = `false`
	)

static

Write header data to a HDF container file.

Parameters

fname	Name of HDF container file
name	Identifier of group holding header information
desc	Custom comment describing dataset
overwrite	Force overwrite if file/group exists; optional (default=`false`)

Definition at line 949 of file SolutionArray.cpp.

◆ writeHeader() [2/2]

void writeHeader	(	AnyMap &	root,
		const string &	name,
		const string &	desc,
		bool	overwrite = `false`
	)

static

Write header data to AnyMap.

Used by YAML serialization.

Parameters

root	Root node of AnyMap structure
name	Identifier of node holding header information
desc	Custom comment describing dataset
overwrite	Force overwrite if node exists; optional (default=`false`)

Definition at line 964 of file SolutionArray.cpp.

◆ writeEntry() [1/3]

void writeEntry	(	const string &	fname,
		bool	overwrite = `false`,
		const string &	basis = `""`
	)

Write SolutionArray data to a CSV file.

Parameters

fname	Name of CSV file
overwrite	Force overwrite if file exists; optional (default=`false`)
basis	Output mass (`"Y"`/`"mass"`) or mole (`"X"`/`"mole"`) fractions; if omitted (default=`""`), the native basis of the underlying ThermoPhase manager is used - see Phase::nativeState

Definition at line 975 of file SolutionArray.cpp.

◆ writeEntry() [2/3]

void writeEntry	(	const string &	fname,
		const string &	name,
		const string &	sub,
		bool	overwrite = `false`,
		int	compression = `0`
	)

Write SolutionArray data to a HDF container file.

Parameters

fname	Name of HDF container file
name	Identifier of group holding header information
sub	Name identifier of subgroup holding SolutionArray data
overwrite	Force overwrite if subgroup exists; optional (default=`false`)
compression	Compression level; optional (default=0; HDF only)

Definition at line 1105 of file SolutionArray.cpp.

◆ writeEntry() [3/3]

void writeEntry	(	AnyMap &	root,
		const string &	name,
		const string &	sub,
		bool	overwrite = `false`
	)

Write SolutionArray data to AnyMap.

Used by YAML serialization.

Parameters

root	Root node of AnyMap structure
name	Identifier of node holding header information and subgroup
sub	Name identifier of subgroup holding SolutionArray data
overwrite	Force overwrite if subgroup exists; optional (default=`false`)

Definition at line 1179 of file SolutionArray.cpp.

◆ save()

void save	(	const string &	fname,
		const string &	name = `""`,
		const string &	sub = `""`,
		const string &	desc = `""`,
		bool	overwrite = `false`,
		int	compression = `0`,
		const string &	basis = `""`
	)

Save current SolutionArray contents to a data file.

Data can be saved either in CSV format (extension *.csv), YAML container format (extension *.yaml/*.yml) or HDF container format (extension *.h5/*.hdf5/*.hdf). The output format is automatically inferred from the file extension.

CSV files preserve state data and auxiliary data for a single SolutionArray in a comma-separated text format, container files may hold multiple SolutionArray entries in an internal hierarchical structure. While YAML is a human-readable text format, HDF is a binary format that supports compression and is recommended for large datasets.

For container files (YAML and HDF), header information contains automatically generated time stamps, version information and an optional description. Container files also preserve SolutionArray metadata (example: SolutionArray objects generated by Sim1D hold simulation settings).

Parameters

fname	Name of output file (CSV, YAML or HDF)
name	Identifier of location within the container file; this node/group contains header information and a subgroup holding actual SolutionArray data (YAML/HDF only)
sub	Name identifier for the subgroup holding the SolutionArray data and metadata objects. If omitted (`""`), the subgroup name defaults to `"data"` (YAML/HDF only)
desc	Custom comment describing dataset to be stored (YAML/HDF only)
overwrite	Force overwrite if file and/or data entry exists; optional (default=`false`)
compression	Compression level (0-9); (default=0; HDF only)
basis	Output mass (`"Y"`/`"mass"`) or mole (`"X"`/`"mole"`) fractions; if not specified (default=`""`), the native basis of the underlying ThermoPhase manager is used - see Phase::nativeState (CSV only)

Definition at line 1277 of file SolutionArray.cpp.

◆ readHeader() [1/2]

AnyMap readHeader	(	const string &	fname,
		const string &	name
	)

static

Read header information from a HDF container file.

Parameters

fname	Name of HDF container file
name	Identifier of group holding header information

Definition at line 1323 of file SolutionArray.cpp.

◆ readHeader() [2/2]

AnyMap readHeader	(	const AnyMap &	root,
		const string &	name
	)

static

Read header information from AnyMap.

Used by YAML serialization.

Parameters

root	Root node of AnyMap structure
name	Identifier of node holding header information

Definition at line 1353 of file SolutionArray.cpp.

◆ readEntry() [1/2]

void readEntry	(	const string &	fname,
		const string &	name,
		const string &	sub
	)

Restore SolutionArray data from a HDF container file.

Parameters

fname	Name of HDF container file
name	Identifier of group holding header information
sub	Name identifier of subgroup holding SolutionArray data

Definition at line 1622 of file SolutionArray.cpp.

◆ readEntry() [2/2]

void readEntry	(	const AnyMap &	root,
		const string &	name,
		const string &	sub
	)

Restore SolutionArray data from AnyMap.

Used by YAML serialization.

Parameters

root	Root node of AnyMap structure
name	Identifier of node holding header information
sub	Name identifier of subgroup holding SolutionArray data

Definition at line 1788 of file SolutionArray.cpp.

◆ restore()

AnyMap restore	(	const string &	fname,
		const string &	name,
		const string &	sub = `""`
	)

Restore SolutionArray data and header information from a container file.

This method retrieves data from a YAML or HDF files that were previously saved using the save() method.

Parameters

fname	Name of container file (YAML or HDF)
name	Identifier of location within the container file; this node/group contains header information and a subgroup holding actual SolutionArray data
sub	Name identifier for the subgroup holding the SolutionArray data and metadata objects. If omitted (`""`), the subgroup name defaults to "data"

Returns: AnyMap containing header information

Definition at line 1365 of file SolutionArray.cpp.

◆ _resize()

void _resize ( size_t size )

protected

Service function used to resize SolutionArray.

Definition at line 190 of file SolutionArray.cpp.

◆ _initExtra()

void _initExtra	(	const string &	name,
		const AnyValue &	value
	)

protected

Initialize extra SolutionArray component.

Parameters

name	Name of component (property defining auxiliary variable)
value	Default value; used to determine type of component

Definition at line 1391 of file SolutionArray.cpp.

◆ _resizeExtra()

void _resizeExtra	(	const string &	name,
		const AnyValue &	value = `AnyValue()`
	)

protected

Resize extra SolutionArray component.

Parameters

name	Name of component (property defining auxiliary variable)
value	Default value

Definition at line 1431 of file SolutionArray.cpp.

◆ _setExtra()

void _setExtra	(	const string &	name,
		const AnyValue &	data = `AnyValue()`
	)

protected

Set extra SolutionArray component.

Parameters

name	Name of component (property defining auxiliary variable)
data	Value to be set

Definition at line 1468 of file SolutionArray.cpp.

◆ _detectMode()

string _detectMode	(	const set< string > &	names,
		bool	native = `true`
	)

protected

Identify storage mode of state data.

The storage mode is a combination of properties defining state); valid modes include Phase::nativeState ("native") or other property combinations defined by Phase::fullStates (three-letter acronyms, for example "TDY", "TPX").

Definition at line 1534 of file SolutionArray.cpp.

◆ _stateProperties()

set< string > _stateProperties	(	const string &	mode,
		bool	alias = `false`
	)

protected

Retrieve set containing list of properties defining state.

Definition at line 1592 of file SolutionArray.cpp.

Member Data Documentation

◆ m_sol

shared_ptr<Solution> m_sol

protected

Solution object associated with state data.

Definition at line 380 of file SolutionArray.h.

◆ m_size

size_t m_size

protected

Number of entries in SolutionArray.

Definition at line 381 of file SolutionArray.h.

◆ m_dataSize

size_t m_dataSize

protected

Total size of unsliced data.

Definition at line 382 of file SolutionArray.h.

◆ m_stride

size_t m_stride

protected

Stride between SolutionArray entries.

Definition at line 383 of file SolutionArray.h.

◆ m_meta

AnyMap m_meta

protected

Metadata.

Definition at line 384 of file SolutionArray.h.

◆ m_loc

size_t m_loc = npos

protected

Buffered location within data vector.

Definition at line 385 of file SolutionArray.h.

◆ m_apiShape

vector<long int> m_apiShape

protected

Shape information used by high-level API's.

Definition at line 386 of file SolutionArray.h.

◆ m_data

shared_ptr<vector<double> > m_data

protected

Work vector holding states.

Definition at line 388 of file SolutionArray.h.

◆ m_extra

shared_ptr<map<string, AnyValue> > m_extra

protected

Auxiliary (extra) components; size of first dimension has to match m_dataSize.

Definition at line 391 of file SolutionArray.h.

◆ m_order

shared_ptr<map<int, string> > m_order

protected

Mapping of auxiliary component names, where the index is used as the mapping key.

Names with index >= zero are listed before state components, while names with index < zero are added at end. The name with the most negative index corresponds to the last entry (different from Python index convention).

Definition at line 397 of file SolutionArray.h.

◆ m_shared

bool m_shared = false

protected

true if data are shared from another object

Definition at line 399 of file SolutionArray.h.

◆ m_active

vector<int> m_active

protected

Vector of locations referencing active entries.

Definition at line 400 of file SolutionArray.h.

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

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Constructor & Destructor Documentation

◆ SolutionArray() [1/2]

◆ SolutionArray() [2/2]

◆ ~SolutionArray()

Member Function Documentation

◆ create()

◆ share()

◆ reset()

◆ size()

◆ resize()

◆ apiShape()

◆ setApiShape()

◆ apiNdim()

◆ info()

◆ meta()

◆ setMeta()

◆ solution()

◆ thermo()

◆ componentNames()

◆ hasComponent()

◆ getComponent()

◆ setComponent()

◆ setLoc()

◆ updateState()

◆ getState()

◆ setState()

◆ normalize()

◆ addExtra()

◆ hasExtra()

◆ listExtra()

◆ getAuxiliary()

◆ setAuxiliary()

◆ append()

◆ writeHeader() [1/2]

◆ writeHeader() [2/2]

◆ writeEntry() [1/3]

◆ writeEntry() [2/3]

◆ writeEntry() [3/3]

◆ save()

◆ readHeader() [1/2]

◆ readHeader() [2/2]

◆ readEntry() [1/2]

◆ readEntry() [2/2]

◆ restore()

◆ _resize()

◆ _initExtra()

◆ _resizeExtra()

◆ _setExtra()

◆ _detectMode()

◆ _stateProperties()

Member Data Documentation

◆ m_sol

◆ m_size

◆ m_dataSize

◆ m_stride

◆ m_meta

◆ m_loc

◆ m_apiShape

◆ m_data

◆ m_extra

◆ m_order

◆ m_shared

◆ m_active