Cantera  2.1.2
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 // Copyright 2001 California Institute of Technology
8 
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/ct_thread.h"
17 
18 namespace Cantera
19 {
20 
21 class SpeciesThermoFactory;
22 class VPSSMgr;
23 
24 /*!
25  * @addtogroup thermoprops
26  *
27  * Standard %ThermoPhase objects may be instantiated by calling
28  * the main %Cantera factory class for %ThermoPhase objects; This class is called ThermoFactory.
29  */
30 //@{
31 
32 //! Specific error to be thrown if the type of Thermo manager is unrecognized.
33 /*!
34  * This particular error class may be caught, if the application may have other
35  * models that the main Cantera application doesn't know about.
36  */
38 {
39 public:
40  //! Constructor
41  /*!
42  * @param proc Function name where the error occurred.
43  * @param thermoModel Sting name of ThermoPhase which didn't match
44  */
45  UnknownThermoPhaseModel(const std::string& proc,
46  const std::string& thermoModel) :
47  CanteraError(proc, "Specified ThermoPhase model "
48  + thermoModel +
49  " does not match any known type.") {}
50 };
51 
52 
53 //! Factory class for thermodynamic property managers.
54 /*!
55  * This class keeps a list of the known ThermoPhase classes, and is
56  * used to create new instances of these classes.
57  */
58 class ThermoFactory : public FactoryBase
59 {
60 
61 public:
62 
63  //! Static function that creates a static instance of the factory.
64  static ThermoFactory* factory() {
65  ScopedLock lock(thermo_mutex);
66  if (!s_factory) {
68  }
69  return s_factory;
70  }
71 
72  //! delete the static instance of this factory
73  virtual void deleteFactory() {
74  ScopedLock lock(thermo_mutex);
75  if (s_factory) {
76  delete s_factory;
77  s_factory = 0;
78  }
79  }
80 
81  //! Create a new thermodynamic property manager.
82  /*!
83  * @param model String to look up the model against
84  *
85  * @return
86  * Returns a pointer to a new ThermoPhase instance matching the
87  * model string. Returns NULL if something went wrong.
88  * Throws an exception UnknownThermoPhaseModel if the string
89  * wasn't matched.
90  */
91  virtual ThermoPhase* newThermoPhase(const std::string& model);
92 
93 private:
94  //! static member of a single instance
96 
97  //! Private constructors prevents usage
99 
100  //! Decl for locking mutex for thermo factory singleton
101  static mutex_t thermo_mutex;
102 };
103 
104 //! Create a new thermo manager instance.
105 /*!
106  * @param model String to look up the model against
107  * @param f ThermoFactor instance to use in matching the string
108  *
109  * @return
110  * Returns a pointer to a new ThermoPhase instance matching the
111  * model string. Returns NULL if something went wrong.
112  * Throws an exception UnknownThermoPhaseModel if the string
113  * wasn't matched.
114  */
115 inline ThermoPhase* newThermoPhase(const std::string& model,
116  ThermoFactory* f=0)
117 {
118  if (f == 0) {
120  }
121  return f->newThermoPhase(model);
122 }
123 
124 //! Translate the eosType id into a string
125 /*!
126  * Returns a string representation of the eosType id for a phase.
127  * @param ieos eosType id of the phase. This is unique for the phase
128  * @param length maximum length of the return string. Defaults to 100
129  *
130  * @return returns a string representation.
131  */
132 std::string eosTypeString(int ieos, int length = 100);
133 
134 //! Create a new ThermoPhase object and initializes it according to the XML
135 //! tree.
136 /*!
137  * This routine first looks up the identity of the model for the solution
138  * thermodynamics in the model attribute of the thermo child of the xml phase
139  * node. Then, it does a string lookup using Cantera's internal ThermoPhase
140  * Factory routines on the model to figure out what ThermoPhase derived class
141  * should be assigned. It creates a new instance of that class, and then calls
142  * importPhase() to populate that class with the correct parameters from the
143  * XML tree.
144  *
145  * @param phase XML_Node reference pointing to the phase XML element.
146  * @return A pointer to the completed and initialized ThermoPhase object.
147  *
148  * @ingroup inputfiles
149  */
150 ThermoPhase* newPhase(XML_Node& phase);
151 
152 //! Create and Initialize a ThermoPhase object from an XML input file.
153 /*!
154  * This routine is a wrapper around the newPhase(XML_Node) routine
155  * which does the work. The wrapper locates the input phase XML_Node
156  * in a file, and then instantiates the object, returning the pointer
157  * to the ThermoPhase object.
158  *
159  * @param infile name of the input file
160  * @param id name of the phase id in the file.
161  * If this is blank, the first phase in the file is used.
162  *
163  * @return
164  * Returns an initialized ThermoPhase object.
165  */
166 ThermoPhase* newPhase(const std::string& infile, std::string id);
167 
168 //! Import a phase information into an empty thermophase object
169 /*!
170  * Here we read an XML description of the thermodynamic information
171  * for a phase. At the end of this routine, the phase should
172  * be ready to be used within applications. This routine contains
173  * some key routines that are used as pass back routines so that
174  * the phase (and the contents of the XML file) may contain
175  * variable parameterizations for the specification of the
176  * species standard states, the equation of state, and the
177  * specification of other nonidealities. Below, a description
178  * is presented of the main algorithm for bringing up a %ThermoPhase
179  * object, with care to present points where customizations
180  * occur.
181  *
182  * Before invoking this routine, either the ThermoPhase Factory routines
183  * are called or direct constructor routines are called that
184  * instantiate an inherited ThermoPhase object. This object is input
185  * to this routine, and therefore contains inherited routines that
186  * drive the customization of the initialization process.
187  *
188  * At the start of the routine, we import descriptions of the elements
189  * that make up the species in a phase.
190  *
191  * We call setParametersFromXML(eos) to read parameters about
192  * the thermo phase before the species are read in.
193  *
194  * We call addElementsFromXML() to add elements into the
195  * description of the phase.
196  *
197  * We create a new species thermo manager. Function
198  * 'newSpeciesThermoMgr' looks at the species in the database
199  * to see what thermodynamic property parameterizations are
200  * used, and selects a class that can handle the
201  * parameterizations found.
202  *
203  * We import information about the species, including their
204  * reference state thermodynamic polynomials. We then freeze
205  * the state of the species in the element.
206  *
207  * Finally, we call initThermoXML(),
208  * a member function of the ThermoPhase object, to "finish"
209  * the description. Now that the species are known,
210  * additional information may be read in about the thermodynamics
211  * of the phase, (e.g., virial coefficients, which are
212  * binary or ternary interaction parameters between species).
213  *
214  * @param phase This object must be the phase node of a
215  * complete XML tree
216  * description of the phase, including all of the
217  * species data. In other words while "phase" must
218  * point to an XML phase object, it must have
219  * sibling nodes "speciesData" that describe
220  * the species in the phase.
221  * @param th Pointer to the ThermoPhase object which will
222  * handle the thermodynamics for this phase.
223  * We initialize part of the Thermophase object
224  * here, especially for those objects which are
225  * part of the Cantera Kernel.
226  *
227  * @param spfactory species Thermo factory pointer, if
228  * available. If not available, one will be
229  * created.
230  *
231  * @ingroup thermoprops
232  */
233 bool importPhase(XML_Node& phase, ThermoPhase* th, SpeciesThermoFactory* spfactory = 0);
234 
235 //! Install a species into a ThermoPhase object, which defines
236 //! the phase thermodynamics and speciation.
237 /*!
238  * This routine first gathers the information from the Species XML
239  * tree and calls addUniqueSpecies() to add it to the
240  * ThermoPhase object, p.
241  * This information consists of:
242  * ecomp[] = element composition of species.
243  * chgr = electric charge of species
244  * name = string name of species
245  * sz = size of the species
246  * (option double used a lot in thermo)
247  *
248  * Then, the routine processes the "thermo" XML element and
249  * calls underlying utility routines to read the XML elements
250  * containing the thermodynamic information for the reference
251  * state of the species. Failures or lack of information trigger
252  * an "UnknownSpeciesThermoModel" exception being thrown.
253  *
254  * @param k Species Index in the phase
255  * @param s XML_Node containing the species data for this species.
256  * @param p Reference to the ThermoPhase object.
257  * @param spthermo_ptr Reference to the SpeciesThermo object, where
258  * the standard state thermo properties for this
259  * species will be installed.
260  * @param rule Parameter that handles what to do with species
261  * who have elements that aren't declared.
262  * Check that all elements in the species
263  * exist in 'p'. If rule != 0, quietly skip
264  * this species if some elements are undeclared;
265  * otherwise, throw an exception
266  * @param phaseNode_ptr Pointer to the XML_Node for this phase
267  * (defaults to 0)
268  * @param vpss_ptr pointer to the Manager that calculates standard
269  * state thermo properties
270  * @param factory Pointer to the SpeciesThermoFactory .
271  * (defaults to 0)
272  *
273  * @return
274  * Returns true if everything is ok, false otherwise.
275  */
276 bool installSpecies(size_t k, const XML_Node& s, thermo_t& p,
277  SpeciesThermo* spthermo_ptr, int rule,
278  XML_Node* phaseNode_ptr = 0,
279  VPSSMgr* vpss_ptr = 0,
280  SpeciesThermoFactory* factory = 0);
281 
282 //! Search an XML tree for species data.
283 /*!
284  * This utility routine will search the XML tree for the species
285  * named by the string, kname. It will return the XML_Node
286  * pointer to the species data for that species.
287  * Failures of any kind return the null pointer.
288  *
289  * @param kname String containing the name of the species.
290  * @param phaseSpeciesData Pointer to the XML speciesData element
291  * containing the species data for that phase.
292  *
293  *
294  */
295 const XML_Node* speciesXML_Node(const std::string& kname,
296  const XML_Node* phaseSpeciesData);
297 
298 //@}
299 
300 }
301 
302 #endif
303 
304 
Specific error to be thrown if the type of Thermo manager is unrecognized.
Definition: ThermoFactory.h:37
virtual void deleteFactory()
delete the static instance of this factory
Definition: ThermoFactory.h:73
ThermoPhase * newPhase(XML_Node &xmlphase)
Create a new ThermoPhase object and initializes it according to the XML tree.
std::string eosTypeString(int ieos, int length)
Translate the eosType id into a string.
bool installSpecies(size_t k, const XML_Node &s, thermo_t &th, SpeciesThermo *spthermo_ptr, int rule, XML_Node *phaseNode_ptr, VPSSMgr *vpss_ptr, SpeciesThermoFactory *factory)
Install a species into a ThermoPhase object, which defines the phase thermodynamics and speciation...
static mutex_t thermo_mutex
Decl for locking mutex for thermo factory singleton.
Definition: ThermoFactory.h:98
static ThermoFactory * factory()
Static function that creates a static instance of the factory.
Definition: ThermoFactory.h:64
Base class for factories.
Definition: FactoryBase.h:18
const XML_Node * speciesXML_Node(const std::string &kname, const XML_Node *phaseSpeciesData)
Search an XML tree for species data.
UnknownThermoPhaseModel(const std::string &proc, const std::string &thermoModel)
Constructor.
Definition: ThermoFactory.h:45
Factory class for thermodynamic property managers.
Definition: ThermoFactory.h:58
ThermoPhase thermo_t
typedef for the ThermoPhase class
Definition: ThermoPhase.h:1684
Base class for a phase with thermodynamic properties.
Definition: ThermoPhase.h:101
bool importPhase(XML_Node &phase, ThermoPhase *th, SpeciesThermoFactory *spfactory)
Import a phase information into an empty thermophase object.
virtual ThermoPhase * newThermoPhase(const std::string &model)
Create a new thermodynamic property manager.
Classes providing support for XML data files.
Base class for exceptions thrown by Cantera classes.
Definition: ctexceptions.h:68
static ThermoFactory * s_factory
static member of a single instance
Definition: ThermoFactory.h:95
ThermoPhase * newThermoPhase(const std::string &model, ThermoFactory *f=0)
Create a new thermo manager instance.
ThermoFactory()
Private constructors prevents usage.
Definition: ThermoFactory.h:98
Header file for class ThermoPhase, the base class for phases with thermodynamic properties, and the text for the Module thermoprops (see Thermodynamic Properties and class ThermoPhase).
File contains the FactoryBase class declarations.