Loading [MathJax]/extensions/tex2jax.js
Cantera  3.2.0a1
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Solution.h
Go to the documentation of this file.
1//! @file Solution.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_SOLUTION_H
7#define CT_SOLUTION_H
8
10#include "cantera/base/AnyMap.h"
11
12namespace Cantera
13{
14
15class ThermoPhase;
16class Kinetics;
17class Transport;
18class ExternalHandle;
19
20//! @defgroup solnGroup Objects Representing Phases
21//! High-level interface to %Cantera's core objects.
22
23//! A container class for chemically-reacting solutions.
24/*!
25 * The Solution class collects all objects needed to describe a chemically-reacting
26 * solution. Instances can be created to represent any type of solution -- a mixture
27 * of gases, a liquid solution, or a solid solution, for example.
28 *
29 * Solution objects only define a small number of methods of their own, and are provided
30 * so that a single object can be used to access thermodynamic, kinetic, and transport
31 * properties of a solution:
32 * - ThermoPhase manager; accessed via thermo()
33 * - Kinetics manager; accessed via kinetics()
34 * - Transport manager; accessed via transport()
35 *
36 * The most common way to instantiate Solution objects is by using a phase definition,
37 * species and reactions defined in an input file:
38 * @code
39 * shared_ptr<Solution> sol = newSolution("gri30.yaml", "gri30");
40 * @endcode
41 * @ingroup solnGroup
42 */
43class Solution : public std::enable_shared_from_this<Solution>
44{
45protected:
46 Solution() = default;
47
48public:
49 virtual ~Solution() = default;
50 Solution(const Solution&) = delete;
51 Solution& operator=(const Solution&) = delete;
52
53 //! Create an empty Solution object
54 static shared_ptr<Solution> create() {
55 return shared_ptr<Solution>( new Solution );
56 }
57
58 //! Return the name of this Solution object
59 string name() const;
60
61 //! Set the name of this Solution object
62 void setName(const string& name);
63
64 //! Set the ThermoPhase object
65 virtual void setThermo(shared_ptr<ThermoPhase> thermo);
66
67 //! Set the Kinetics object
68 virtual void setKinetics(shared_ptr<Kinetics> kinetics);
69
70 //! Set the Transport object directly
71 virtual void setTransport(shared_ptr<Transport> transport);
72
73 //! Retrieve transport model name
74 //! @since New in %Cantera 3.2
75 string transportModel();
76
77 //! Set the Transport object by name
78 //! @param model name of transport model; if omitted, the default model is used
79 //! @since New in %Cantera 3.0
80 void setTransportModel(const string& model="default");
81
82 //! Accessor for the ThermoPhase pointer
83 shared_ptr<ThermoPhase> thermo() {
84 return m_thermo;
85 }
86
87 //! Accessor for the Kinetics pointer
88 shared_ptr<Kinetics> kinetics() {
89 return m_kinetics;
90 }
91
92 //! Accessor for the Transport pointer
93 shared_ptr<Transport> transport() {
94 return m_transport;
95 }
96
97 //! Add a phase adjacent to this phase. Usually this means a higher-dimensional
98 //! phase that participates in reactions in this phase.
99 void addAdjacent(shared_ptr<Solution> adjacent);
100
101 //! Get the Solution object for an adjacent phase by index
102 shared_ptr<Solution> adjacent(size_t i) {
103 return m_adjacent.at(i);
104 }
105
106 //! Get the Solution object for an adjacent phase by name
107 shared_ptr<Solution> adjacent(const string& name) {
108 return m_adjacentByName.at(name);
109 }
110
111 //! Get the number of adjacent phases
112 size_t nAdjacent() const {
113 return m_adjacent.size();
114 }
115
116 //! Get the name of an adjacent phase by index
117 string adjacentName(size_t i) const {
118 if (i >= m_adjacent.size()) {
119 throw IndexError("Solution::adjacentName", "m_adjacent",
120 i, m_adjacent.size());
121 }
122 return m_adjacent.at(i)->name();
123 }
124
125 AnyMap parameters(bool withInput=false) const;
126
127 //! Access input data associated with header definition
128 const AnyMap& header() const;
129 AnyMap& header();
130
131 //! Retrieve source used for object creation; usually an input file name
132 const string source() const;
133
134 //! Overwrite source (only required if object is not created using newSolution)
135 void setSource(const string& source);
136
137 //! Store a handle to a wrapper for this Solution object from an external
138 //! language interface (for example, a Python Solution object)
139 void holdExternalHandle(const string& name, shared_ptr<ExternalHandle> handle);
140
141 //! Get the handle for a wrapper for this Solution object from an external
142 //! language interface.
143 //! Returns a null pointer if the requested handle does not exist.
144 shared_ptr<ExternalHandle> getExternalHandle(const string& name) const;
145
146 //! Register a function to be called if any of the Solution's thermo, kinetics,
147 //! or transport objects is replaced.
148 //! @param id A unique ID corresponding to the object affected by the callback.
149 //! Typically, this is a pointer to an object that also holds a reference to the
150 //! Solution object.
151 //! @param callback The callback function to be called after any component of the
152 //! Solution is replaced.
153 //! When the callback becomes invalid (for example, the corresponding object is
154 //! being deleted, the removeChangedCallback() method must be invoked.
155 //! @since New in %Cantera 3.0
156 void registerChangedCallback(void* id, const function<void()>& callback);
157
158 //! Remove the callback function associated with the specified object.
159 //! @since New in %Cantera 3.0
160 void removeChangedCallback(void* id);
161
162protected:
163 shared_ptr<ThermoPhase> m_thermo; //!< ThermoPhase manager
164 shared_ptr<Kinetics> m_kinetics; //!< Kinetics manager
165 shared_ptr<Transport> m_transport; //!< Transport manager
166
167 //! Adjacent phases, for access by index
168 vector<shared_ptr<Solution>> m_adjacent;
169
170 //! Adjacent phases, for access by name
171 map<string, shared_ptr<Solution>> m_adjacentByName;
172
173 AnyMap m_header; //!< Additional input fields; usually from a YAML input file
174
175 //! Wrappers for this Solution object in extension languages, for evaluation
176 //! of user-defined reaction rates
177 map<string, shared_ptr<ExternalHandle>> m_externalHandles;
178
179 //! Callback functions that are invoked when the therm, kinetics, or transport
180 //! members of the Solution are replaced.
181 map<void*, function<void()>> m_changeCallbacks;
182};
183
184//! Create and initialize a new Solution from an input file
185/*!
186 * This constructor wraps newThermo(), newKinetics() and newTransport() routines
187 * for initialization.
188 *
189 * @param infile name of the input file
190 * @param name name of the phase in the file. If this is blank, the first phase
191 * in the file is used.
192 * @param transport name of the transport model. If blank, the transport model specified
193 * in the phase definition is used.
194 * @param adjacent vector containing names of adjacent phases that participate in this
195 * phases kinetics. If empty, adjacent phases will be instantiated based
196 * on the phase definition.
197 * @returns an initialized Solution object.
198 * @ingroup solnGroup
199 */
200shared_ptr<Solution> newSolution(const string& infile, const string& name,
201 const string& transport, const vector<string>& adjacent);
202
203//! Create and initialize a new Solution manager from an input file
204/*!
205 * This constructor wraps newThermo(), newKinetics() and newTransport() routines
206 * for initialization.
207 *
208 * @param infile name of the input file
209 * @param name name of the phase in the file.
210 * If this is blank, the first phase in the file is used.
211 * @param transport name of the transport model.
212 * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
213 * phases will be instantiated based on the phase definition.
214 * @returns an initialized Solution object.
215 * @ingroup solnGroup
216 */
217shared_ptr<Solution> newSolution(const string& infile,
218 const string& name="",
219 const string& transport="default",
220 const vector<shared_ptr<Solution>>& adjacent={});
221
222//! Create and initialize a new Solution manager from AnyMap objects
223/*!
224 * This constructor wraps newThermo(), newKinetics() and newTransport() routines
225 * for initialization.
226 *
227 * @param phaseNode the node containing the phase definition (that is, thermo model,
228 * list of species, and initial state)
229 * @param rootNode the root node of the tree containing the phase definition, which
230 * will be used as the default location from which to read species definitions.
231 * @param transport name of the transport model.
232 * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
233 * phases will be instantiated based on the phase definition.
234 * @param related vector of phases related to the same root Solution object. Used
235 * internally by newSolution() when creating complex interfaces where
236 * a phase may be adjacent to multiple other phases but should be
237 * instantiated only once.
238 * @returns an initialized Solution object.
239 * @ingroup solnGroup
240 */
241shared_ptr<Solution> newSolution(
242 const AnyMap& phaseNode, const AnyMap& rootNode=AnyMap(),
243 const string& transport="default",
244 const vector<shared_ptr<Solution>>& adjacent={},
245 const map<string, shared_ptr<Solution>>& related={});
246
247}
248
249#endif
A map of string keys to values whose type can vary at runtime.
Definition AnyMap.h:432
An array index is out of range.
A container class for chemically-reacting solutions.
Definition Solution.h:44
static shared_ptr< Solution > create()
Create an empty Solution object.
Definition Solution.h:54
vector< shared_ptr< Solution > > m_adjacent
Adjacent phases, for access by index.
Definition Solution.h:168
string transportModel()
Retrieve transport model name.
Definition Solution.cpp:64
string adjacentName(size_t i) const
Get the name of an adjacent phase by index.
Definition Solution.h:117
void removeChangedCallback(void *id)
Remove the callback function associated with the specified object.
Definition Solution.cpp:186
map< string, shared_ptr< Solution > > m_adjacentByName
Adjacent phases, for access by name.
Definition Solution.h:171
void setSource(const string &source)
Overwrite source (only required if object is not created using newSolution)
Definition Solution.cpp:161
shared_ptr< Kinetics > kinetics()
Accessor for the Kinetics pointer.
Definition Solution.h:88
void setTransportModel(const string &model="default")
Set the Transport object by name.
Definition Solution.cpp:83
void addAdjacent(shared_ptr< Solution > adjacent)
Add a phase adjacent to this phase.
Definition Solution.cpp:94
void setName(const string &name)
Set the name of this Solution object.
Definition Solution.cpp:34
shared_ptr< Kinetics > m_kinetics
Kinetics manager.
Definition Solution.h:164
virtual void setThermo(shared_ptr< ThermoPhase > thermo)
Set the ThermoPhase object.
Definition Solution.cpp:43
map< string, shared_ptr< ExternalHandle > > m_externalHandles
Wrappers for this Solution object in extension languages, for evaluation of user-defined reaction rat...
Definition Solution.h:177
shared_ptr< ThermoPhase > m_thermo
ThermoPhase manager.
Definition Solution.h:163
void registerChangedCallback(void *id, const function< void()> &callback)
Register a function to be called if any of the Solution's thermo, kinetics, or transport objects is r...
Definition Solution.cpp:181
AnyMap m_header
Additional input fields; usually from a YAML input file.
Definition Solution.h:173
size_t nAdjacent() const
Get the number of adjacent phases.
Definition Solution.h:112
void holdExternalHandle(const string &name, shared_ptr< ExternalHandle > handle)
Store a handle to a wrapper for this Solution object from an external language interface (for example...
Definition Solution.cpp:166
map< void *, function< void()> > m_changeCallbacks
Callback functions that are invoked when the therm, kinetics, or transport members of the Solution ar...
Definition Solution.h:181
shared_ptr< Solution > adjacent(const string &name)
Get the Solution object for an adjacent phase by name.
Definition Solution.h:107
const string source() const
Retrieve source used for object creation; usually an input file name.
Definition Solution.cpp:156
virtual void setTransport(shared_ptr< Transport > transport)
Set the Transport object directly.
Definition Solution.cpp:73
shared_ptr< ThermoPhase > thermo()
Accessor for the ThermoPhase pointer.
Definition Solution.h:83
shared_ptr< Transport > transport()
Accessor for the Transport pointer.
Definition Solution.h:93
const AnyMap & header() const
Access input data associated with header definition.
Definition Solution.cpp:146
shared_ptr< Solution > adjacent(size_t i)
Get the Solution object for an adjacent phase by index.
Definition Solution.h:102
shared_ptr< Transport > m_transport
Transport manager.
Definition Solution.h:165
virtual void setKinetics(shared_ptr< Kinetics > kinetics)
Set the Kinetics object.
Definition Solution.cpp:51
shared_ptr< ExternalHandle > getExternalHandle(const string &name) const
Get the handle for a wrapper for this Solution object from an external language interface.
Definition Solution.cpp:172
string name() const
Return the name of this Solution object.
Definition Solution.cpp:25
Definitions for the classes that are thrown when Cantera experiences an error condition (also contain...
shared_ptr< Solution > newSolution(const string &infile, const string &name, const string &transport, const vector< shared_ptr< Solution > > &adjacent)
Create and initialize a new Solution manager from an input file.
Definition Solution.cpp:191
Namespace for the Cantera kernel.
Definition AnyMap.cpp:595