Cantera  3.1.0a1
SolutionArray Class Reference

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< SolutionArrayshare (const vector< int > &selected)
 Share locations from an existing SolutionArray and return new reference. More...
 
void reset ()
 Reset all entries of the SolutionArray to the current Solution state. More...
 
int size () const
 Size of SolutionArray (number of entries). More...
 
void resize (int size)
 Resize SolutionArray objects with a single dimension (default). More...
 
vector< long int > apiShape () const
 SolutionArray shape information used by high-level API's. More...
 
void setApiShape (const vector< long int > &shape)
 Set SolutionArray shape information used by high-level API's. More...
 
int apiNdim () const
 Number of SolutionArray dimensions used by high-level API's. More...
 
string info (const vector< string > &keys, int rows=10, int width=80)
 Print a concise summary of a SolutionArray. More...
 
AnyMapmeta ()
 SolutionArray meta data. More...
 
void setMeta (const AnyMap &meta)
 Set SolutionArray meta data. More...
 
shared_ptr< Solutionsolution ()
 Retrieve associated Solution object. More...
 
shared_ptr< ThermoPhasethermo ()
 Retrieve associated ThermoPhase object. More...
 
vector< string > componentNames () const
 Retrieve list of component names. More...
 
bool hasComponent (const string &name) const
 Check whether SolutionArray contains a component. More...
 
AnyValue getComponent (const string &name) const
 Retrieve a component of the SolutionArray by name. More...
 
void setComponent (const string &name, const AnyValue &data)
 Set a component of the SolutionArray by name. More...
 
void setLoc (int loc, bool restore=true)
 Update the buffered location used to access SolutionArray entries. More...
 
void updateState (int loc)
 Update state at given location to state of associated Solution object. More...
 
vector< double > getState (int loc)
 Retrieve the state vector for a given location. More...
 
void setState (int loc, const vector< double > &state)
 Set the state vector for a given location. More...
 
void normalize ()
 Normalize mass/mole fractions. More...
 
void addExtra (const string &name, bool back=true)
 Add auxiliary component to SolutionArray. More...
 
bool hasExtra (const string &name) const
 Check whether SolutionArray contains an extra component. More...
 
vector< string > listExtra (bool all=true) const
 Retrieve list of extra component names. More...
 
AnyMap getAuxiliary (int loc)
 Retrieve auxiliary data for a given location. More...
 
void setAuxiliary (int loc, const AnyMap &data)
 Set auxiliary data for a given location. More...
 
void append (const vector< double > &state, const AnyMap &extra)
 Append location entry at end of SolutionArray. More...
 
void writeEntry (const string &fname, bool overwrite=false, const string &basis="")
 Write SolutionArray data to a CSV file. More...
 
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. More...
 
void writeEntry (AnyMap &root, const string &name, const string &sub, bool overwrite=false)
 Write SolutionArray data to AnyMap. More...
 
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. More...
 
void readEntry (const string &fname, const string &name, const string &sub)
 Restore SolutionArray data from a HDF container file. More...
 
void readEntry (const AnyMap &root, const string &name, const string &sub)
 Restore SolutionArray data from AnyMap. More...
 
AnyMap restore (const string &fname, const string &name, const string &sub="")
 Restore SolutionArray data and header information from a container file. More...
 

Static Public Member Functions

static shared_ptr< SolutionArraycreate (const shared_ptr< Solution > &sol, int size=0, const AnyMap &meta={})
 Instantiate a new SolutionArray reference. More...
 
static void writeHeader (const string &fname, const string &name, const string &desc, bool overwrite=false)
 Write header data to a HDF container file. More...
 
static void writeHeader (AnyMap &root, const string &name, const string &desc, bool overwrite=false)
 Write header data to AnyMap. More...
 
static AnyMap readHeader (const string &fname, const string &name)
 Read header information from a HDF container file. More...
 
static AnyMap readHeader (const AnyMap &root, const string &name)
 Read header information from AnyMap. More...
 

Protected Member Functions

void _resize (size_t size)
 Service function used to resize SolutionArray. More...
 
void _initExtra (const string &name, const AnyValue &value)
 Initialize extra SolutionArray component. More...
 
void _resizeExtra (const string &name, const AnyValue &value=AnyValue())
 Resize extra SolutionArray component. More...
 
void _setExtra (const string &name, const AnyValue &data=AnyValue())
 Set extra SolutionArray component. More...
 
string _detectMode (const set< string > &names, bool native=true)
 Identify storage mode of state data. More...
 
set< string > _stateProperties (const string &mode, bool alias=false)
 Retrieve set containing list of properties defining state. More...
 

Protected Attributes

shared_ptr< Solutionm_sol
 Solution object associated with state data. More...
 
size_t m_size
 Number of entries in SolutionArray. More...
 
size_t m_dataSize
 Total size of unsliced data. More...
 
size_t m_stride
 Stride between SolutionArray entries. More...
 
AnyMap m_meta
 Metadata. More...
 
size_t m_loc = npos
 Buffered location within data vector. More...
 
vector< long int > m_apiShape
 Shape information used by high-level API's. More...
 
shared_ptr< vector< double > > m_data
 Work vector holding states. More...
 
shared_ptr< map< string, AnyValue > > m_extra
 Auxiliary (extra) components; size of first dimension has to match m_dataSize. More...
 
shared_ptr< map< int, string > > m_order
 Mapping of auxiliary component names, where the index is used as the mapping key. More...
 
bool m_shared = false
 true if data are shared from another object More...
 
vector< int > m_active
 Vector of locations referencing active entries. More...
 

Private Member Functions

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

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
solSolution object defining phase definitions
sizeNumber of SolutionArray entries
metaAnyMap 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
selectedList 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
keysList of components to be displayed; if empty, all components are considered.
rowsMaximum number of rendered rows.
widthMaximum 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
nameName of component (property defining auxiliary variable)
dataComponent 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
nameName of component (property defining auxiliary variable)
backIf 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
fnameName of HDF container file
nameIdentifier of group holding header information
descCustom comment describing dataset
overwriteForce 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
rootRoot node of AnyMap structure
nameIdentifier of node holding header information
descCustom comment describing dataset
overwriteForce 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
fnameName of CSV file
overwriteForce overwrite if file exists; optional (default=false)
basisOutput 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
fnameName of HDF container file
nameIdentifier of group holding header information
subName identifier of subgroup holding SolutionArray data
overwriteForce overwrite if subgroup exists; optional (default=false)
compressionCompression 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
rootRoot node of AnyMap structure
nameIdentifier of node holding header information and subgroup
subName identifier of subgroup holding SolutionArray data
overwriteForce 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
fnameName of output file (CSV, YAML or HDF)
nameIdentifier of location within the container file; this node/group contains header information and a subgroup holding actual SolutionArray data (YAML/HDF only)
subName identifier for the subgroup holding the SolutionArray data and metadata objects. If omitted (""), the subgroup name defaults to "data" (YAML/HDF only)
descCustom comment describing dataset to be stored (YAML/HDF only)
overwriteForce overwrite if file and/or data entry exists; optional (default=false)
compressionCompression level (0-9); (default=0; HDF only)
basisOutput 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
fnameName of HDF container file
nameIdentifier 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
rootRoot node of AnyMap structure
nameIdentifier 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
fnameName of HDF container file
nameIdentifier of group holding header information
subName 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
rootRoot node of AnyMap structure
nameIdentifier of node holding header information
subName 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
fnameName of container file (YAML or HDF)
nameIdentifier of location within the container file; this node/group contains header information and a subgroup holding actual SolutionArray data
subName 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
nameName of component (property defining auxiliary variable)
valueDefault 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
nameName of component (property defining auxiliary variable)
valueDefault 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
nameName of component (property defining auxiliary variable)
dataValue 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: