Cantera 2.6.0

ThermoFactory.h
Go to the documentation of this file.
1/**
2 * @file ThermoFactory.h
3 * Headers for the factory class that can create known ThermoPhase objects
4 * (see \ref thermoprops and class \link Cantera::ThermoFactory ThermoFactory\endlink).
5 */
6
7// This file is part of Cantera. See License.txt in the top-level directory or
8// at https://cantera.org/license.txt for license and copyright information.
9
10#ifndef THERMO_FACTORY_H
11#define THERMO_FACTORY_H
12
13#include "ThermoPhase.h"
14#include "cantera/base/xml.h"
15#include "cantera/base/FactoryBase.h"
16
17 namespace Cantera
18{
19
20/*!
21 * @addtogroup thermoprops
22 *
23 * Standard ThermoPhase objects may be instantiated by calling the main %Cantera
24 * factory class for ThermoPhase objects; This class is called ThermoFactory.
25 */
26//@{
27
28//! Specific error to be thrown if the type of Thermo manager is unrecognized.
29/*!
30 * This particular error class may be caught, if the application may have other
31 * models that the main Cantera application doesn't know about.
32 *
33 * @deprecated Unused. To be removed after Cantera 2.6.
34 */
35 class UnknownThermoPhaseModel : public CanteraError
36{
37 public:
38 //! Constructor
39 /*!
40 * @param proc Function name where the error occurred.
41 * @param thermoModel Sting name of ThermoPhase which didn't match
42 */
43 UnknownThermoPhaseModel(const std::string& proc,
44 const std::string& thermoModel) :
45 CanteraError(proc, "Specified ThermoPhase model "
46 + thermoModel +
47 " does not match any known type.") {
48 warn_deprecated("class UnknownThermoPhaseModel",
49 "Unused. To be removed after Cantera 2.6.");
50 }
51};
52
53
54//! Factory class for thermodynamic property managers.
55/*!
56 * This class keeps a list of the known ThermoPhase classes, and is
57 * used to create new instances of these classes.
58 */
59 class ThermoFactory : public Factory<ThermoPhase>
60{
61 public:
62 //! Static function that creates a static instance of the factory.
63 static ThermoFactory* factory() {
64 std::unique_lock<std::mutex> lock(thermo_mutex);
65 if (!s_factory) {
66 s_factory = new ThermoFactory;
67 }
68 return s_factory;
69 }
70
71 //! delete the static instance of this factory
72 virtual void deleteFactory() {
73 std::unique_lock<std::mutex> lock(thermo_mutex);
74 delete s_factory;
75 s_factory = 0;
76 }
77
78 //! Create a new thermodynamic property manager.
79 /*!
80 * @param model The name of the thermo model
81 * @returns a pointer to a new ThermoPhase object of the type specified. Throws a
82 * CanteraError if the named model isn't registered with ThermoFactory.
83 */
84 virtual ThermoPhase* newThermoPhase(const std::string& model);
85
86 private:
87 //! static member of a single instance
88 static ThermoFactory* s_factory;
89
90 //! Private constructors prevents usage
91 ThermoFactory();
92
93 //! Decl for locking mutex for thermo factory singleton
94 static std::mutex thermo_mutex;
95};
96
97//! @copydoc ThermoFactory::newThermoPhase
98 inline ThermoPhase* newThermoPhase(const std::string& model)
99{
100 return ThermoFactory::factory()->create(model);
101}
102
103//! Create a new ThermoPhase instance.
104/*!
105 * @param model String to look up the model against
106 * @returns a shared pointer to a new ThermoPhase instance matching the model string.
107 */
108 inline shared_ptr<ThermoPhase> newThermo(const std::string& model)
109{
110 ThermoPhase* tptr = ThermoFactory::factory()->create(model);
111 return shared_ptr<ThermoPhase> (tptr);
112}
113
114//! Create a new ThermoPhase object and initializes it according to the XML tree
115/*!
116 * This routine first looks up the identity of the model for the solution
117 * thermodynamics in the model attribute of the thermo child of the XML phase
118 * node. Then, it does a string lookup using Cantera's internal ThermoPhase
119 * Factory routines on the model to figure out what ThermoPhase derived class
120 * should be assigned. It creates a new instance of that class, and then calls
121 * importPhase() to populate that class with the correct parameters from the
122 * XML tree.
123 *
124 * @param phase XML_Node reference pointing to the phase XML element.
125 * @return A pointer to the completed and initialized ThermoPhase object.
126 *
127 * @ingroup inputfiles
128 *
129 * @deprecated The XML input format is deprecated and will be removed in
130 * Cantera 3.0.
131 */
132ThermoPhase* newPhase(XML_Node& phase);
133
134//! Create a new ThermoPhase object and initialize it
135/*!
136 * @param phaseNode The node containing the phase definition (that is, thermo
137 * model, list of species, and initial state)
138 * @param rootNode The root node of the tree containing the phase definition,
139 * which will be used as the default location from which to read species
140 * definitions.
141 */
142unique_ptr<ThermoPhase> newPhase(const AnyMap& phaseNode,
143 const AnyMap& rootNode=AnyMap());
144
145//! Create and Initialize a ThermoPhase object from an input file.
146/*!
147 * For YAML input files, this function uses AnyMap::fromYamlFile() to read the
148 * input file, newThermoPhase() to create an empty ThermoPhase of the
149 * appropriate type, and setupPhase() to initialize the phase.
150 *
151 * For CTI and XML input files, this function uses get_XML_File() to read the
152 * input file and newPhase(XML_Node) to create and initialize the phase.
153 *
154 * @param infile name of the input file
155 * @param id name (id) of the phase in the file.
156 * If this is blank, the first phase in the file is used.
157 * @returns an initialized ThermoPhase object.
158 */
159ThermoPhase* newPhase(const std::string& infile, std::string id="");
160
161//! Import a phase information into an empty ThermoPhase object
162/*!
163 * Here we read an XML description of the thermodynamic information for a phase.
164 * At the end of this routine, the phase should be ready to be used within
165 * applications. This routine contains some key routines that are used as pass
166 * back routines so that the phase (and the contents of the XML file) may
167 * contain variable parameterizations for the specification of the species
168 * standard states, the equation of state, and the specification of other
169 * nonidealities. Below, a description is presented of the main algorithm for
170 * bringing up a ThermoPhase object, with care to present points where
171 * customizations occur.
172 *
173 * Before invoking this routine, either the ThermoPhase Factory routines are
174 * called or direct constructor routines are called that instantiate an
175 * inherited ThermoPhase object. This object is input to this routine, and
176 * therefore contains inherited routines that drive the customization of the
177 * initialization process.
178 *
179 * At the start of the routine, we import descriptions of the elements that make
180 * up the species in a phase.
181 *
182 * We call setParametersFromXML(eos) to read parameters about the thermo phase
183 * before the species are read in.
184 *
185 * We call addElementsFromXML() to add elements into the description of the
186 * phase.
187 *
188 * We create a new species thermo manager. Function 'newSpeciesThermoMgr' looks
189 * at the species in the database to see what thermodynamic property
190 * parameterizations are used, and selects a class that can handle the
191 * parameterizations found.
192 *
193 * We import information about the species, including their reference state
194 * thermodynamic polynomials. We then freeze the state of the species in the
195 * element.
196 *
197 * Finally, we call initThermoXML(), a member function of the ThermoPhase
198 * object, to "finish" the description. Now that the species are known,
199 * additional information may be read in about the thermodynamics of the phase,
200 * (for example, virial coefficients, which are binary or ternary interaction
201 * parameters between species).
202 *
203 * @param phase This object must be the phase node of a complete XML tree
204 * description of the phase, including all of the species data. In
205 * other words while "phase" must point to an XML phase object, it
206 * must have sibling nodes "speciesData" that describe the species
207 * in the phase.
208 * @param th Pointer to the ThermoPhase object which will handle the
209 * thermodynamics for this phase. We initialize part of the
210 * ThermoPhase object here, especially for those objects which are
211 * part of the Cantera Kernel.
212 * @ingroup thermoprops
213 *
214 * @deprecated The XML input format is deprecated and will be removed in
215 * Cantera 3.0.
216 */
217 void importPhase(XML_Node& phase, ThermoPhase* th);
218
219//! Initialize a ThermoPhase object
220/*!
221 * @param phase The ThermoPhase object to be initialized
222 * @param phaseNode The node containing the phase definition (that is, thermo
223 * model, list of species, and initial state)
224 * @param rootNode The root node of the tree containing the phase definition,
225 * which will be used as the default location from which to read species
226 * definitions.
227 */
228 void setupPhase(ThermoPhase& phase, const AnyMap& phaseNode,
229 const AnyMap& rootNode=AnyMap());
230
231//! Add the elements given in an XML_Node tree to the specified phase
232//!
233//! @deprecated The XML input format is deprecated and will be removed in
234//! Cantera 3.0.
235 void installElements(Phase& th, const XML_Node& phaseNode);
236
237//! Search an XML tree for species data.
238/*!
239 * This utility routine will search the XML tree for the species named by the
240 * string, kname. It will return the XML_Node pointer to the species data for
241 * that species. Failures of any kind return the null pointer.
242 *
243 * @param kname String containing the name of the species.
244 * @param phaseSpeciesData Pointer to the XML speciesData element
245 * containing the species data for that phase.
246 *
247 * @deprecated The XML input format is deprecated and will be removed in
248 * Cantera 3.0.
249 */
250 const XML_Node* speciesXML_Node(const std::string& kname,
251 const XML_Node* phaseSpeciesData);
252
253//@}
254
255}
256
257#endif
FactoryBase.h
File contains the FactoryBase class declarations.
ThermoPhase.h
Header file for class ThermoPhase, the base class for phases with thermodynamic properties,...
Cantera::CanteraError
Base class for exceptions thrown by Cantera classes.
Definition: ctexceptions.h:61
Cantera::Factory
Factory class that supports registering functions to create objects.
Definition: FactoryBase.h:70
Cantera::Factory::create
T * create(const std::string &name, Args... args)
Create an object using the object construction function corresponding to "name" and the provided cons...
Definition: FactoryBase.h:76
Cantera::ThermoFactory
Factory class for thermodynamic property managers.
Definition: ThermoFactory.h:60
Cantera::ThermoFactory::ThermoFactory
ThermoFactory()
Private constructors prevents usage.
Definition: ThermoFactory.cpp:50
Cantera::ThermoFactory::thermo_mutex
static std::mutex thermo_mutex
Decl for locking mutex for thermo factory singleton.
Definition: ThermoFactory.h:94
Cantera::ThermoFactory::newThermoPhase
virtual ThermoPhase * newThermoPhase(const std::string &model)
Create a new thermodynamic property manager.
Definition: ThermoFactory.cpp:109
Cantera::ThermoFactory::deleteFactory
virtual void deleteFactory()
delete the static instance of this factory
Definition: ThermoFactory.h:72
Cantera::ThermoFactory::s_factory
static ThermoFactory * s_factory
static member of a single instance
Definition: ThermoFactory.h:88
Cantera::ThermoFactory::factory
static ThermoFactory * factory()
Static function that creates a static instance of the factory.
Definition: ThermoFactory.h:63
Cantera::ThermoPhase
Base class for a phase with thermodynamic properties.
Definition: ThermoPhase.h:102
Cantera::UnknownThermoPhaseModel
Specific error to be thrown if the type of Thermo manager is unrecognized.
Definition: ThermoFactory.h:36
Cantera::UnknownThermoPhaseModel::UnknownThermoPhaseModel
UnknownThermoPhaseModel(const std::string &proc, const std::string &thermoModel)
Constructor.
Definition: ThermoFactory.h:43
Cantera::newPhase
ThermoPhase * newPhase(XML_Node &xmlphase)
Create a new ThermoPhase object and initializes it according to the XML tree.
Definition: ThermoFactory.cpp:114
Cantera::importPhase
void importPhase(XML_Node &phase, ThermoPhase *th)
Import a phase information into an empty ThermoPhase object.
Definition: ThermoFactory.cpp:250
Cantera
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:557
Cantera::setupPhase
void setupPhase(ThermoPhase &thermo, const AnyMap &phaseNode, const AnyMap &rootNode)
Initialize a ThermoPhase object.
Definition: ThermoFactory.cpp:460
Cantera::warn_deprecated
void warn_deprecated(const std::string &source, const AnyBase &node, const std::string &message)
A deprecation warning for syntax in an input file.
Definition: AnyMap.cpp:1901
Cantera::speciesXML_Node
const XML_Node * speciesXML_Node(const std::string &kname, const XML_Node *phaseSpeciesData)
Search an XML tree for species data.
Definition: ThermoFactory.cpp:666
Cantera::installElements
void installElements(Phase &th, const XML_Node &phaseNode)
Add the elements given in an XML_Node tree to the specified phase.
Definition: ThermoFactory.cpp:605
Cantera::newThermo
shared_ptr< ThermoPhase > newThermo(const std::string &model)
Create a new ThermoPhase instance.
Definition: ThermoFactory.h:108
Cantera::newThermoPhase
ThermoPhase * newThermoPhase(const std::string &model)
Create a new thermodynamic property manager.
Definition: ThermoFactory.h:98
xml.h
Classes providing support for XML data files.