Cantera  3.1.0a1
Loading...
Searching...
No Matches
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 //! Set the Transport object by name
74 //! @param model name of transport model; if omitted, the default model is used
75 //! @since New in %Cantera 3.0
76 void setTransportModel(const string& model="");
77
78 //! Accessor for the ThermoPhase pointer
79 shared_ptr<ThermoPhase> thermo() {
80 return m_thermo;
81 }
82
83 //! Accessor for the Kinetics pointer
84 shared_ptr<Kinetics> kinetics() {
85 return m_kinetics;
86 }
87
88 //! Accessor for the Transport pointer
89 shared_ptr<Transport> transport() {
90 return m_transport;
91 }
92
93 //! Add a phase adjacent to this phase. Usually this means a higher-dimensional
94 //! phase that participates in reactions in this phase.
95 void addAdjacent(shared_ptr<Solution> adjacent);
96
97 //! Get the Solution object for an adjacent phase by index
98 shared_ptr<Solution> adjacent(size_t i) {
99 return m_adjacent.at(i);
100 }
101
102 //! Get the Solution object for an adjacent phase by name
103 shared_ptr<Solution> adjacent(const string& name) {
104 return m_adjacentByName.at(name);
105 }
106
107 //! Get the number of adjacent phases
108 size_t nAdjacent() const {
109 return m_adjacent.size();
110 }
111
112 AnyMap parameters(bool withInput=false) const;
113
114 //! Access input data associated with header definition
115 const AnyMap& header() const;
116 AnyMap& header();
117
118 //! Retrieve source used for object creation; usually an input file name
119 const string source() const;
120
121 //! Overwrite source (only required if object is not created using newSolution)
122 void setSource(const string& source);
123
124 //! Store a handle to a wrapper for this Solution object from an external
125 //! language interface (for example, a Python Solution object)
126 void holdExternalHandle(const string& name, shared_ptr<ExternalHandle> handle);
127
128 //! Get the handle for a wrapper for this Solution object from an external
129 //! language interface.
130 //! Returns a null pointer if the requested handle does not exist.
131 shared_ptr<ExternalHandle> getExternalHandle(const string& name) const;
132
133 //! Register a function to be called if any of the Solution's thermo, kinetics,
134 //! or transport objects is replaced.
135 //! @param id A unique ID corresponding to the object affected by the callback.
136 //! Typically, this is a pointer to an object that also holds a reference to the
137 //! Solution object.
138 //! @param callback The callback function to be called after any component of the
139 //! Solution is replaced.
140 //! When the callback becomes invalid (for example, the corresponding object is
141 //! being deleted, the removeChangedCallback() method must be invoked.
142 //! @since New in %Cantera 3.0
143 void registerChangedCallback(void* id, const function<void()>& callback);
144
145 //! Remove the callback function associated with the specified object.
146 //! @since New in %Cantera 3.0
147 void removeChangedCallback(void* id);
148
149protected:
150 shared_ptr<ThermoPhase> m_thermo; //!< ThermoPhase manager
151 shared_ptr<Kinetics> m_kinetics; //!< Kinetics manager
152 shared_ptr<Transport> m_transport; //!< Transport manager
153
154 //! Adjacent phases, for access by index
155 vector<shared_ptr<Solution>> m_adjacent;
156
157 //! Adjacent phases, for access by name
158 map<string, shared_ptr<Solution>> m_adjacentByName;
159
160 AnyMap m_header; //!< Additional input fields; usually from a YAML input file
161
162 //! Wrappers for this Solution object in extension languages, for evaluation
163 //! of user-defined reaction rates
164 map<string, shared_ptr<ExternalHandle>> m_externalHandles;
165
166 //! Callback functions that are invoked when the therm, kinetics, or transport
167 //! members of the Solution are replaced.
168 map<void*, function<void()>> m_changeCallbacks;
169};
170
171//! Create and initialize a new Solution from an input file
172/*!
173 * This constructor wraps newThermo(), newKinetics() and newTransport() routines
174 * for initialization.
175 *
176 * @param infile name of the input file
177 * @param name name of the phase in the file. If this is blank, the first phase
178 * in the file is used.
179 * @param transport name of the transport model. If blank, the transport model specified
180 * in the phase definition is used.
181 * @param adjacent vector containing names of adjacent phases that participate in this
182 * phases kinetics. If empty, adjacent phases will be instantiated based
183 * on the phase definition.
184 * @returns an initialized Solution object.
185 * @ingroup solnGroup
186 */
187shared_ptr<Solution> newSolution(const string& infile, const string& name,
188 const string& transport, const vector<string>& adjacent);
189
190//! Create and initialize a new Solution manager from an input file
191/*!
192 * This constructor wraps newThermo(), newKinetics() and newTransport() routines
193 * for initialization.
194 *
195 * @param infile name of the input file
196 * @param name name of the phase in the file.
197 * If this is blank, the first phase in the file is used.
198 * @param transport name of the transport model.
199 * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
200 * phases will be instantiated based on the phase definition.
201 * @returns an initialized Solution object.
202 * @ingroup solnGroup
203 */
204shared_ptr<Solution> newSolution(const string& infile,
205 const string& name="",
206 const string& transport="",
207 const vector<shared_ptr<Solution>>& adjacent={});
208
209//! Create and initialize a new Solution manager from AnyMap objects
210/*!
211 * This constructor wraps newThermo(), newKinetics() and newTransport() routines
212 * for initialization.
213 *
214 * @param phaseNode the node containing the phase definition (that is, thermo model,
215 * list of species, and initial state)
216 * @param rootNode the root node of the tree containing the phase definition, which
217 * will be used as the default location from which to read species definitions.
218 * @param transport name of the transport model.
219 * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
220 * phases will be instantiated based on the phase definition.
221 * @param related vector of phases related to the same root Solution object. Used
222 * internally by newSolution() when creating complex interfaces where
223 * a phase may be adjacent to multiple other phases but should be
224 * instantiated only once.
225 * @returns an initialized Solution object.
226 * @ingroup solnGroup
227 */
228shared_ptr<Solution> newSolution(
229 const AnyMap& phaseNode, const AnyMap& rootNode=AnyMap(),
230 const string& transport="",
231 const vector<shared_ptr<Solution>>& adjacent={},
232 const map<string, shared_ptr<Solution>>& related={});
233
234}
235
236#endif
A map of string keys to values whose type can vary at runtime.
Definition AnyMap.h:427
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:155
void removeChangedCallback(void *id)
Remove the callback function associated with the specified object.
Definition Solution.cpp:177
map< string, shared_ptr< Solution > > m_adjacentByName
Adjacent phases, for access by name.
Definition Solution.h:158
void setSource(const string &source)
Overwrite source (only required if object is not created using newSolution)
Definition Solution.cpp:152
shared_ptr< Kinetics > kinetics()
Accessor for the Kinetics pointer.
Definition Solution.h:84
void addAdjacent(shared_ptr< Solution > adjacent)
Add a phase adjacent to this phase.
Definition Solution.cpp:85
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:151
void setTransportModel(const string &model="")
Set the Transport object by name.
Definition Solution.cpp:73
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:164
shared_ptr< ThermoPhase > m_thermo
ThermoPhase manager.
Definition Solution.h:150
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:172
AnyMap m_header
Additional input fields; usually from a YAML input file.
Definition Solution.h:160
size_t nAdjacent() const
Get the number of adjacent phases.
Definition Solution.h:108
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:157
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:168
shared_ptr< Solution > adjacent(const string &name)
Get the Solution object for an adjacent phase by name.
Definition Solution.h:103
const string source() const
Retrieve source used for object creation; usually an input file name.
Definition Solution.cpp:147
virtual void setTransport(shared_ptr< Transport > transport)
Set the Transport object directly.
Definition Solution.cpp:63
shared_ptr< ThermoPhase > thermo()
Accessor for the ThermoPhase pointer.
Definition Solution.h:79
shared_ptr< Transport > transport()
Accessor for the Transport pointer.
Definition Solution.h:89
const AnyMap & header() const
Access input data associated with header definition.
Definition Solution.cpp:137
shared_ptr< Solution > adjacent(size_t i)
Get the Solution object for an adjacent phase by index.
Definition Solution.h:98
shared_ptr< Transport > m_transport
Transport manager.
Definition Solution.h:152
virtual void setKinetics(shared_ptr< Kinetics > kinetics)
Set the Kinetics object.
Definition Solution.cpp:50
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:163
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:182
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564