Cantera  3.0.0
Loading...
Searching...
No Matches
SolutionArray.h
Go to the documentation of this file.
1//! @file SolutionArray.h
2
3// This file is part of Cantera. See License.txt in the top-level directory or
4// at https://cantera.org/license.txt for license and copyright information.
5
6#ifndef CT_SOLUTIONARRAY_H
7#define CT_SOLUTIONARRAY_H
8
10#include "cantera/base/AnyMap.h"
11
12namespace Cantera
13{
14
15class Solution;
16class ThermoPhase;
17
18//! A container class holding arrays of state information.
19/*!
20 * SolutionArray objects provide a convenient interface for representing many
21 * thermodynamic states using the same Solution object. C++ SolutionArray objects are
22 * one-dimensional by design; while shape information for multi-dimensional arrays is
23 * stored, reshaping operations need to be implemented in high-level API's.
24 *
25 * The SolutionArray class implements the main interface for saving and restoring of
26 * %Cantera simulation data. SolutionArray objects can be serialized to and from YAML and
27 * HDF container files using the save() and restore() methods. In addition, there is
28 * limited support for CSV files.
29 * @since New in %Cantera 3.0.
30 * @ingroup solnGroup
31 */
33{
34private:
35 SolutionArray(const shared_ptr<Solution>& sol,
36 int size,
37 const AnyMap& meta);
38
39 SolutionArray(const SolutionArray& arr, const vector<int>& indices);
40
41public:
42 virtual ~SolutionArray() {}
43
44 /**
45 * Instantiate a new SolutionArray reference.
46 *
47 * @param sol Solution object defining phase definitions
48 * @param size Number of SolutionArray entries
49 * @param meta AnyMap holding SolutionArray meta data
50 */
51 static shared_ptr<SolutionArray> create(const shared_ptr<Solution>& sol,
52 int size=0,
53 const AnyMap& meta={})
54 {
55 return shared_ptr<SolutionArray>(new SolutionArray(sol, size, meta));
56 }
57
58 /**
59 * Share locations from an existing SolutionArray and return new reference.
60 *
61 * Both SolutionArray object share common data. The method is used for slicing
62 * of SolutionArrays from high-level API's. Note that meta data are not inherited.
63 * @param selected List of locations for shared entries
64 */
65 shared_ptr<SolutionArray> share(const vector<int>& selected)
66 {
67 return shared_ptr<SolutionArray>(new SolutionArray(*this, selected));
68 }
69
70 //! Reset all entries of the SolutionArray to the current Solution state
71 void reset();
72
73 //! Size of SolutionArray (number of entries).
74 int size() const {
75 return static_cast<int>(m_size);
76 }
77
78 //! Resize SolutionArray objects with a single dimension (default).
79 void resize(int size);
80
81 //! SolutionArray shape information used by high-level API's.
82 vector<long int> apiShape() const {
83 return m_apiShape;
84 }
85
86 //! Set SolutionArray shape information used by high-level API's.
87 //! The size of the SolutionArray is adjusted automatically.
88 void setApiShape(const vector<long int>& shape);
89
90 //! Number of SolutionArray dimensions used by high-level API's.
91 int apiNdim() const {
92 return static_cast<int>(m_apiShape.size());
93 }
94
95 /**
96 * Print a concise summary of a SolutionArray.
97 * @param keys List of components to be displayed; if empty, all components are
98 * considered.
99 * @param rows Maximum number of rendered rows.
100 * @param width Maximum width of rendered output.
101 */
102 string info(const vector<string>& keys, int rows=10, int width=80);
103
104 //! SolutionArray meta data.
106 return m_meta;
107 }
108
109 //! Set SolutionArray meta data.
110 void setMeta(const AnyMap& meta) {
111 m_meta = meta;
112 }
113
114 //! Retrieve associated Solution object
115 shared_ptr<Solution> solution() {
116 return m_sol;
117 }
118
119 //! Retrieve associated ThermoPhase object
120 shared_ptr<ThermoPhase> thermo();
121
122 //! Retrieve list of component names
123 vector<string> componentNames() const;
124
125 /**
126 * Check whether SolutionArray contains a component.
127 * A component is a property defining state or auxiliary variable.
128 */
129 bool hasComponent(const string& name) const;
130
131 /**
132 * Retrieve a component of the SolutionArray by name.
133 * Returns an AnyValue containing an array with length size() with a type
134 * specific to the component; in most cases, the type is double, but may differ
135 * for auxiliary data.
136 */
137 AnyValue getComponent(const string& name) const;
138
139 /**
140 * Set a component of the SolutionArray by name.
141 * The passed AnyValue should containing an array with length size() with a type
142 * specific to the component; in most cases, the type is double, but may differ
143 * for auxiliary data.
144 *
145 * @param name Name of component (property defining auxiliary variable)
146 * @param data Component data
147 */
148 void setComponent(const string& name, const AnyValue& data);
149
150 /**
151 * Update the buffered location used to access SolutionArray entries.
152 */
153 void setLoc(int loc, bool restore=true);
154
155 /**
156 * Update state at given location to state of associated Solution object.
157 */
158 void updateState(int loc);
159
160 //! Retrieve the state vector for a given location.
161 vector<double> getState(int loc);
162
163 //! Set the state vector for a given location.
164 void setState(int loc, const vector<double>& state);
165
166 //! Normalize mass/mole fractions
167 void normalize();
168
169 /**
170 * Add auxiliary component to SolutionArray. Initialization requires a subsequent
171 * call of setComponent().
172 *
173 * @param name Name of component (property defining auxiliary variable)
174 * @param back If `true` (default), add name after components representing the
175 * state, otherwise add to front of list. Front and back components are
176 * populated left to right.
177 */
178 void addExtra(const string& name, bool back=true);
179
180 //! Check whether SolutionArray contains an extra component
181 bool hasExtra(const string& name) const {
182 return m_extra->count(name);
183 }
184
185 //! Retrieve list of extra component names
186 vector<string> listExtra(bool all=true) const;
187
188 //! Retrieve auxiliary data for a given location.
189 AnyMap getAuxiliary(int loc);
190
191 //! Set auxiliary data for a given location.
192 void setAuxiliary(int loc, const AnyMap& data);
193
194 //! Append location entry at end of SolutionArray.
195 void append(const vector<double>& state, const AnyMap& extra);
196
197 /**
198 * Write header data to a HDF container file.
199 *
200 * @param fname Name of HDF container file
201 * @param name Identifier of group holding header information
202 * @param desc Custom comment describing dataset
203 * @param overwrite Force overwrite if file/group exists;
204 * optional (default=`false`)
205 */
206 static void writeHeader(const string& fname, const string& name, const string& desc,
207 bool overwrite=false);
208
209 /**
210 * Write header data to AnyMap. Used by YAML serialization.
211 *
212 * @param root Root node of AnyMap structure
213 * @param name Identifier of node holding header information
214 * @param desc Custom comment describing dataset
215 * @param overwrite Force overwrite if node exists; optional (default=`false`)
216 */
217 static void writeHeader(AnyMap& root, const string& name, const string& desc,
218 bool overwrite=false);
219
220 /**
221 * Write SolutionArray data to a CSV file.
222 *
223 * @param fname Name of CSV file
224 * @param overwrite Force overwrite if file exists; optional (default=`false`)
225 * @param basis Output mass (`"Y"`/`"mass"`) or mole (`"X"`/`"mole"`) fractions;
226 * if omitted (default=`""`), the native basis of the underlying ThermoPhase
227 * manager is used - see Phase::nativeState
228 */
229 void writeEntry(const string& fname, bool overwrite=false, const string& basis="");
230
231 /**
232 * Write SolutionArray data to a HDF container file.
233 *
234 * @param fname Name of HDF container file
235 * @param name Identifier of group holding header information
236 * @param sub Name identifier of subgroup holding SolutionArray data
237 * @param overwrite Force overwrite if subgroup exists; optional (default=`false`)
238 * @param compression Compression level; optional (default=0; HDF only)
239 */
240 void writeEntry(const string& fname, const string& name, const string& sub,
241 bool overwrite=false, int compression=0);
242
243 /**
244 * Write SolutionArray data to AnyMap. Used by YAML serialization.
245 *
246 * @param root Root node of AnyMap structure
247 * @param name Identifier of node holding header information and subgroup
248 * @param sub Name identifier of subgroup holding SolutionArray data
249 * @param overwrite Force overwrite if subgroup exists; optional (default=`false`)
250 */
251 void writeEntry(AnyMap& root, const string& name, const string& sub,
252 bool overwrite=false);
253
254 /**
255 * Save current SolutionArray contents to a data file.
256 *
257 * Data can be saved either in CSV format (extension `*.csv`), YAML container
258 * format (extension `*.yaml`/`*.yml`) or HDF container format (extension
259 * `*.h5`/`*.hdf5`/`*.hdf`). The output format is automatically inferred from the
260 * file extension.
261 *
262 * CSV files preserve state data and auxiliary data for a single SolutionArray in a
263 * comma-separated text format, container files may hold multiple SolutionArray
264 * entries in an internal hierarchical structure. While YAML is a human-readable
265 * text format, HDF is a binary format that supports compression and is recommended
266 * for large datasets.
267 *
268 * For container files (YAML and HDF), header information contains automatically
269 * generated time stamps, version information and an optional description.
270 * Container files also preserve SolutionArray metadata (example: SolutionArray
271 * objects generated by Sim1D hold simulation settings).
272 *
273 * @param fname Name of output file (CSV, YAML or HDF)
274 * @param name Identifier of location within the container file; this node/group
275 * contains header information and a subgroup holding actual SolutionArray data
276 * (YAML/HDF only)
277 * @param sub Name identifier for the subgroup holding the SolutionArray data and
278 * metadata objects. If omitted (`""`), the subgroup name defaults to `"data"`
279 * (YAML/HDF only)
280 * @param desc Custom comment describing dataset to be stored (YAML/HDF only)
281 * @param overwrite Force overwrite if file and/or data entry exists; optional
282 * (default=`false`)
283 * @param compression Compression level (0-9); (default=0; HDF only)
284 * @param basis Output mass (`"Y"`/`"mass"`) or mole (`"X"`/`"mole"`) fractions;
285 * if not specified (default=`""`), the native basis of the underlying
286 * ThermoPhase manager is used - see Phase::nativeState (CSV only)
287 */
288 void save(const string& fname, const string& name="", const string& sub="",
289 const string& desc="", bool overwrite=false, int compression=0,
290 const string& basis="");
291
292 /**
293 * Read header information from a HDF container file.
294 *
295 * @param fname Name of HDF container file
296 * @param name Identifier of group holding header information
297 */
298 static AnyMap readHeader(const string& fname, const string& name);
299
300 /**
301 * Read header information from AnyMap. Used by YAML serialization.
302 *
303 * @param root Root node of AnyMap structure
304 * @param name Identifier of node holding header information
305 */
306 static AnyMap readHeader(const AnyMap& root, const string& name);
307
308 /**
309 * Restore SolutionArray data from a HDF container file.
310 *
311 * @param fname Name of HDF container file
312 * @param name Identifier of group holding header information
313 * @param sub Name identifier of subgroup holding SolutionArray data
314 */
315 void readEntry(const string& fname, const string& name, const string& sub);
316
317 /**
318 * Restore SolutionArray data from AnyMap. Used by YAML serialization.
319 *
320 * @param root Root node of AnyMap structure
321 * @param name Identifier of node holding header information
322 * @param sub Name identifier of subgroup holding SolutionArray data
323 */
324 void readEntry(const AnyMap& root, const string& name, const string& sub);
325
326 /**
327 * Restore SolutionArray data and header information from a container file.
328 *
329 * This method retrieves data from a YAML or HDF files that were previously saved
330 * using the save() method.
331 *
332 * @param fname Name of container file (YAML or HDF)
333 * @param name Identifier of location within the container file; this node/group
334 * contains header information and a subgroup holding actual SolutionArray data
335 * @param sub Name identifier for the subgroup holding the SolutionArray data and
336 * metadata objects. If omitted (`""`), the subgroup name defaults to "data"
337 * @return AnyMap containing header information
338 */
339 AnyMap restore(const string& fname, const string& name, const string& sub="");
340
341protected:
342 //! Service function used to resize SolutionArray
343 void _resize(size_t size);
344
345 /**
346 * Initialize extra SolutionArray component.
347 *
348 * @param name Name of component (property defining auxiliary variable)
349 * @param value Default value; used to determine type of component
350 */
351 void _initExtra(const string& name, const AnyValue& value);
352
353 /**
354 * Resize extra SolutionArray component.
355 *
356 * @param name Name of component (property defining auxiliary variable)
357 * @param value Default value
358 */
359 void _resizeExtra(const string& name, const AnyValue& value=AnyValue());
360
361 /**
362 * Set extra SolutionArray component
363 *
364 * @param name Name of component (property defining auxiliary variable)
365 * @param data Value to be set
366 */
367 void _setExtra(const string& name, const AnyValue& data=AnyValue());
368
369 /**
370 * Identify storage mode of state data. The storage mode is a combination of
371 * properties defining state); valid modes include Phase::nativeState (`"native"`)
372 * or other property combinations defined by Phase::fullStates (three-letter
373 * acronyms, for example `"TDY"`, `"TPX"`).
374 */
375 string _detectMode(const set<string>& names, bool native=true);
376
377 //! Retrieve set containing list of properties defining state
378 set<string> _stateProperties(const string& mode, bool alias=false);
379
380 shared_ptr<Solution> m_sol; //!< Solution object associated with state data
381 size_t m_size; //!< Number of entries in SolutionArray
382 size_t m_dataSize; //!< Total size of unsliced data
383 size_t m_stride; //!< Stride between SolutionArray entries
384 AnyMap m_meta; //!< Metadata
385 size_t m_loc = npos; //!< Buffered location within data vector
386 vector<long int> m_apiShape; //!< Shape information used by high-level API's
387
388 shared_ptr<vector<double>> m_data; //!< Work vector holding states
389
390 //! Auxiliary (extra) components; size of first dimension has to match m_dataSize
391 shared_ptr<map<string, AnyValue>> m_extra;
392
393 //! Mapping of auxiliary component names, where the index is used as the
394 //! mapping key. Names with index >= zero are listed before state components, while
395 //! names with index < zero are added at end. The name with the most negative index
396 //! corresponds to the last entry (different from Python index convention).
397 shared_ptr<map<int, string>> m_order;
398
399 bool m_shared = false; //!< `true` if data are shared from another object
400 vector<int> m_active; //!< Vector of locations referencing active entries
401};
402
403}
404
405#endif
A map of string keys to values whose type can vary at runtime.
Definition AnyMap.h:427
A wrapper for a variable whose type is determined at runtime.
Definition AnyMap.h:86
A container class holding arrays of state information.
size_t m_size
Number of entries in SolutionArray.
AnyMap m_meta
Metadata.
void append(const vector< double > &state, const AnyMap &extra)
Append location entry at end of SolutionArray.
size_t m_loc
Buffered location within data vector.
void setLoc(int loc, bool restore=true)
Update the buffered location used to access SolutionArray entries.
string _detectMode(const set< string > &names, bool native=true)
Identify storage mode of state data.
size_t m_dataSize
Total size of unsliced data.
void setMeta(const AnyMap &meta)
Set SolutionArray meta data.
static AnyMap readHeader(const string &fname, const string &name)
Read header information from a HDF container file.
size_t m_stride
Stride between SolutionArray entries.
shared_ptr< SolutionArray > share(const vector< int > &selected)
Share locations from an existing SolutionArray and return new reference.
void _setExtra(const string &name, const AnyValue &data=AnyValue())
Set extra SolutionArray component.
string info(const vector< string > &keys, int rows=10, int width=80)
Print a concise summary of a SolutionArray.
vector< string > listExtra(bool all=true) const
Retrieve list of extra component names.
void setApiShape(const vector< long int > &shape)
Set SolutionArray shape information used by high-level API's.
void setAuxiliary(int loc, const AnyMap &data)
Set auxiliary data for a given location.
static void writeHeader(const string &fname, const string &name, const string &desc, bool overwrite=false)
Write header data to a HDF container file.
AnyMap restore(const string &fname, const string &name, const string &sub="")
Restore SolutionArray data and header information from a container file.
shared_ptr< Solution > solution()
Retrieve associated Solution object.
AnyMap getAuxiliary(int loc)
Retrieve auxiliary data for a given location.
AnyValue getComponent(const string &name) const
Retrieve a component of the SolutionArray by name.
vector< int > m_active
Vector of locations referencing active entries.
set< string > _stateProperties(const string &mode, bool alias=false)
Retrieve set containing list of properties defining state.
void readEntry(const string &fname, const string &name, const string &sub)
Restore SolutionArray data from a HDF container file.
void _resize(size_t size)
Service function used to resize SolutionArray.
bool hasComponent(const string &name) const
Check whether SolutionArray contains a component.
void _initExtra(const string &name, const AnyValue &value)
Initialize extra SolutionArray component.
vector< string > componentNames() const
Retrieve list of component names.
vector< long int > apiShape() const
SolutionArray 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.
bool m_shared
true if data are shared from another object
void setState(int loc, const vector< double > &state)
Set the state vector for a given location.
shared_ptr< map< int, string > > m_order
Mapping of auxiliary component names, where the index is used as the mapping key.
int apiNdim() const
Number of SolutionArray dimensions used by high-level API's.
void setComponent(const string &name, const AnyValue &data)
Set a component of the SolutionArray by name.
AnyMap & meta()
SolutionArray meta data.
void normalize()
Normalize mass/mole fractions.
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 reset()
Reset all entries of the SolutionArray to the current Solution state.
void resize(int size)
Resize SolutionArray objects with a single dimension (default).
void _resizeExtra(const string &name, const AnyValue &value=AnyValue())
Resize extra SolutionArray component.
shared_ptr< ThermoPhase > thermo()
Retrieve associated ThermoPhase object.
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.
void updateState(int loc)
Update state at given location to state of associated Solution object.
static shared_ptr< SolutionArray > create(const shared_ptr< Solution > &sol, int size=0, const AnyMap &meta={})
Instantiate a new SolutionArray reference.
vector< double > getState(int loc)
Retrieve the state vector for a given location.
void writeEntry(const string &fname, bool overwrite=false, const string &basis="")
Write SolutionArray data to a CSV file.
int size() const
Size of SolutionArray (number of entries).
vector< long int > m_apiShape
Shape information used by high-level API's.
shared_ptr< Solution > m_sol
Solution object associated with state data.
This file contains definitions for utility functions and text for modules, inputfiles and logging,...
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564
const size_t npos
index returned by functions to indicate "no position"
Definition ct_defs.h:195