Cantera
3.1.0a1
|
A container class holding arrays of state information. More...
#include <SolutionArray.h>
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.
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. 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... | |
AnyMap & | meta () |
SolutionArray meta data. More... | |
void | setMeta (const AnyMap &meta) |
Set SolutionArray meta data. More... | |
shared_ptr< Solution > | solution () |
Retrieve associated Solution object. More... | |
shared_ptr< ThermoPhase > | thermo () |
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< SolutionArray > | create (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< Solution > | m_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) | |
|
inlinestatic |
Instantiate a new SolutionArray reference.
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.
|
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.
selected | List of locations for shared entries |
Definition at line 65 of file SolutionArray.h.
void reset | ( | ) |
Reset all entries of the SolutionArray to the current Solution state.
Definition at line 123 of file SolutionArray.cpp.
|
inline |
Size of SolutionArray (number of entries).
Definition at line 74 of file SolutionArray.h.
void resize | ( | int | size | ) |
Resize SolutionArray objects with a single dimension (default).
Definition at line 154 of file SolutionArray.cpp.
|
inline |
SolutionArray shape information used by high-level API's.
Definition at line 82 of file SolutionArray.h.
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.
|
inline |
Number of SolutionArray dimensions used by high-level API's.
Definition at line 91 of file SolutionArray.h.
string info | ( | const vector< string > & | keys, |
int | rows = 10 , |
||
int | width = 80 |
||
) |
Print a concise summary of a SolutionArray.
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.
|
inline |
SolutionArray meta data.
Definition at line 105 of file SolutionArray.h.
|
inline |
Set SolutionArray meta data.
Definition at line 110 of file SolutionArray.h.
|
inline |
Retrieve associated Solution object.
Definition at line 115 of file SolutionArray.h.
shared_ptr< ThermoPhase > thermo | ( | ) |
Retrieve associated ThermoPhase object.
Definition at line 534 of file SolutionArray.cpp.
vector< string > componentNames | ( | ) | const |
Retrieve list of component names.
Definition at line 539 of file SolutionArray.cpp.
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.
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.
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.
name | Name of component (property defining auxiliary variable) |
data | Component data |
Definition at line 704 of file SolutionArray.cpp.
void setLoc | ( | int | loc, |
bool | restore = true |
||
) |
Update the buffered location used to access SolutionArray entries.
Definition at line 739 of file SolutionArray.cpp.
void updateState | ( | int | loc | ) |
Update state at given location to state of associated Solution object.
Definition at line 763 of file SolutionArray.cpp.
vector< double > getState | ( | int | loc | ) |
Retrieve the state vector for a given location.
Definition at line 770 of file SolutionArray.cpp.
void setState | ( | int | loc, |
const vector< double > & | state | ||
) |
Set the state vector for a given location.
Definition at line 779 of file SolutionArray.cpp.
void normalize | ( | ) |
Normalize mass/mole fractions.
Definition at line 792 of file SolutionArray.cpp.
void addExtra | ( | const string & | name, |
bool | back = true |
||
) |
Add auxiliary component to SolutionArray.
Initialization requires a subsequent call of setComponent().
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.
|
inline |
Check whether SolutionArray contains an extra component.
Definition at line 181 of file SolutionArray.h.
vector< string > listExtra | ( | bool | all = true | ) | const |
Retrieve list of extra component names.
Definition at line 598 of file SolutionArray.cpp.
AnyMap getAuxiliary | ( | int | loc | ) |
Retrieve auxiliary data for a given location.
Definition at line 822 of file SolutionArray.cpp.
void setAuxiliary | ( | int | loc, |
const AnyMap & | data | ||
) |
Set auxiliary data for a given location.
Definition at line 850 of file SolutionArray.cpp.
void append | ( | const vector< double > & | state, |
const AnyMap & | extra | ||
) |
Append location entry at end of SolutionArray.
Definition at line 1258 of file SolutionArray.cpp.
|
static |
Write header data to a HDF container file.
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.
|
static |
Write header data to AnyMap.
Used by YAML serialization.
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.
void writeEntry | ( | const string & | fname, |
bool | overwrite = false , |
||
const string & | basis = "" |
||
) |
Write SolutionArray data to a CSV file.
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.
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.
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.
void writeEntry | ( | AnyMap & | root, |
const string & | name, | ||
const string & | sub, | ||
bool | overwrite = false |
||
) |
Write SolutionArray data to AnyMap.
Used by YAML serialization.
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.
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).
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.
|
static |
Read header information from a HDF container file.
fname | Name of HDF container file |
name | Identifier of group holding header information |
Definition at line 1323 of file SolutionArray.cpp.
Read header information from AnyMap.
Used by YAML serialization.
root | Root node of AnyMap structure |
name | Identifier of node holding header information |
Definition at line 1353 of file SolutionArray.cpp.
void readEntry | ( | const string & | fname, |
const string & | name, | ||
const string & | sub | ||
) |
Restore SolutionArray data from a HDF container file.
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.
void readEntry | ( | const AnyMap & | root, |
const string & | name, | ||
const string & | sub | ||
) |
Restore SolutionArray data from AnyMap.
Used by YAML serialization.
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.
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.
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" |
Definition at line 1365 of file SolutionArray.cpp.
|
protected |
Service function used to resize SolutionArray.
Definition at line 190 of file SolutionArray.cpp.
|
protected |
Initialize extra SolutionArray component.
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.
Resize extra SolutionArray component.
name | Name of component (property defining auxiliary variable) |
value | Default value |
Definition at line 1431 of file SolutionArray.cpp.
Set extra SolutionArray component.
name | Name of component (property defining auxiliary variable) |
data | Value to be set |
Definition at line 1468 of file SolutionArray.cpp.
|
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.
|
protected |
Retrieve set containing list of properties defining state.
Definition at line 1592 of file SolutionArray.cpp.
|
protected |
Solution object associated with state data.
Definition at line 380 of file SolutionArray.h.
|
protected |
Number of entries in SolutionArray.
Definition at line 381 of file SolutionArray.h.
|
protected |
Total size of unsliced data.
Definition at line 382 of file SolutionArray.h.
|
protected |
Stride between SolutionArray entries.
Definition at line 383 of file SolutionArray.h.
|
protected |
Metadata.
Definition at line 384 of file SolutionArray.h.
|
protected |
Buffered location within data vector.
Definition at line 385 of file SolutionArray.h.
|
protected |
Shape information used by high-level API's.
Definition at line 386 of file SolutionArray.h.
|
protected |
Work vector holding states.
Definition at line 388 of file SolutionArray.h.
|
protected |
Auxiliary (extra) components; size of first dimension has to match m_dataSize.
Definition at line 391 of file SolutionArray.h.
|
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.
|
protected |
true
if data are shared from another object
Definition at line 399 of file SolutionArray.h.
|
protected |
Vector of locations referencing active entries.
Definition at line 400 of file SolutionArray.h.