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