| Cantera 3.0.0

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Private Member Functions | List of all members
SolutionArray Class Reference
Objects Representing Phases

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 | ( |  | ) |
| inline virtual

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 = `{}`
| ) |  |
| inline static

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:

- SolutionArray.h
- SolutionArray.cpp