Cantera  3.1.0a1
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 
12 namespace Cantera
13 {
14 
15 class ThermoPhase;
16 class Kinetics;
17 class Transport;
18 class 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  */
43 class Solution : public std::enable_shared_from_this<Solution>
44 {
45 protected:
46  Solution() = default;
47 
48 public:
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 
149 protected:
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  */
187 shared_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  */
204 shared_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  */
228 shared_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
shared_ptr< ThermoPhase > thermo()
Accessor for the ThermoPhase pointer.
Definition: Solution.h:79
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
shared_ptr< Kinetics > kinetics()
Accessor for the Kinetics pointer.
Definition: Solution.h:84
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
void addAdjacent(shared_ptr< Solution > adjacent)
Add a phase adjacent to this phase.
Definition: Solution.cpp:85
shared_ptr< Transport > transport()
Accessor for the Transport pointer.
Definition: Solution.h:89
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
shared_ptr< Solution > adjacent(size_t i)
Get the Solution object for an adjacent phase by index.
Definition: Solution.h:98
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
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< Solution > adjacent(const string &name)
Get the Solution object for an adjacent phase by name.
Definition: Solution.h:103
const AnyMap & header() const
Access input data associated with header definition.
Definition: Solution.cpp:137
static shared_ptr< Solution > create()
Create an empty Solution object.
Definition: Solution.h:54
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