Cleaned up Doxygen documentation for thermo factory classes

This commit is contained in:
Ray Speth 2013-03-07 18:51:04 +00:00
parent 0314eef0f7
commit 01b57ba821
7 changed files with 78 additions and 319 deletions

View file

@ -492,8 +492,7 @@
* (both P and T dependent), is to be used to calculate the
* standard state properties of the species within the phase.
* If only a reference state is needed
* then a call to
* \link #Cantera::newSpeciesThermoMgr(std::vector<XML_Node*> spData_nodes, SpeciesThermoFactory* f=0, bool opt=false) newSpeciesThermoMgr()\endlink
* then a call to newSpeciesThermoMgr()
* is made in order
* pick a manager, i.e., a derivative of the SpeciesThermo
* object, to use.

View file

@ -80,11 +80,10 @@ public:
//! Static method to return an instance of this class
/*!
* This class is implemented as a singleton -- one in which
* only one instance is needed. The recommended way to access
* the factory is to call this static method, which
* instantiates the class if it is the first call, but
* otherwise simply returns the pointer to the existing
* This class is implemented as a singleton -- one in which only one
* instance is needed. The recommended way to access the factory is to
* call this static method, which instantiates the class if it is the
* first call, but otherwise simply returns the pointer to the existing
* instance.
*/
static SpeciesThermoFactory* factory();
@ -99,35 +98,25 @@ public:
//! Destructor
/**
* Doesn't do anything. We do not delete statically
* created single instance of this class here, because it would
* create an infinite loop if destructor is called for that
* single instance.
* Doesn't do anything. We do not delete statically created single
* instance of this class here, because it would create an infinite loop
* if destructor is called for that single instance.
*/
virtual ~SpeciesThermoFactory();
//! Create a new species property manage for the reference state.
//! Create a new species property manager for the reference state.
/*!
* @param type the integer type to be created.
*
*
* @return Returns the pointer to the newly malloced
* species property manager for the reference
* state
* @return Returns the pointer to the newly allocated species property
* manager for the reference state
*/
SpeciesThermo* newSpeciesThermo(int type) const;
//! Create a new species thermo property manager given a string
/*!
* Create a new species thermo property manager, given a
* string.
*
* @param stype String name for the species thermo type
*
*
* @return Returns the pointer to the newly malloced
* species property manager for the reference
* state
* @param stype String name for the species thermo type
* @return Returns the pointer to the newly malloced species
* property manager for the reference state
*/
SpeciesThermo* newSpeciesThermoManager(std::string& stype) const;
@ -138,12 +127,10 @@ public:
* each species needs for its species property managers. Then,
* it will malloc and return the proper species property manager to use.
*
* @param spDataNodeList This vector contains a list
* of species XML nodes that will be in the phase
*
* @return Returns the pointer to the newly malloced
* species property manager for the reference
* state
* @param spDataNodeList This vector contains a list of species XML
* nodes that will be in the phase
* @return Returns the pointer to the newly malloced species property
* manager for the reference state
*/
SpeciesThermo* newSpeciesThermo(std::vector<XML_Node*> & spDataNodeList) const;
@ -151,13 +138,12 @@ public:
//! for the reference state for one species into a species thermo manager.
/*!
* @param k Species number
* @param speciesNode Reference to the XML node specifying the species standard
* state information
* @param speciesNode Reference to the XML node specifying the species
* standard state information
* @param th_ptr Pointer to the %ThermoPhase object for the species
* @param spthermo Species reference state thermo manager
* @param phaseNode_ptr Optional pointer to the XML phase
* information for the phase in which the species
* resides
* @param phaseNode_ptr Optional pointer to the XML phase information for
* the phase in which the species resides
*/
void installThermoForSpecies(size_t k, const XML_Node& speciesNode,
ThermoPhase* th_ptr, SpeciesThermo& spthermo,
@ -173,15 +159,14 @@ public:
* read the xml database to extract the constants for these steps.
*
* @param k species number
* @param speciesNode Reference to the XML node specifying the species standard
* state information
* @param speciesNode Reference to the XML node specifying the species
* standard state information
* @param vp_ptr variable pressure ThermoPhase object
* @param vpss_ptr Pointer to the Manager for calculating variable pressure
* substances.
* @param vpss_ptr Pointer to the Manager for calculating variable
* pressure substances.
* @param spthermo_ptr Species reference state thermo manager
* @param phaseNode_ptr Optional Pointer to the XML phase
* information for the phase in which the species
* resides
* @param phaseNode_ptr Optional Pointer to the XML phase information for
* the phase in which the species resides
*/
void installVPThermoForSpecies(size_t k, const XML_Node& speciesNode,
VPStandardStateTP* vp_ptr,
@ -211,15 +196,15 @@ private:
//////////////////////////////////////////////////////////////////
//! Create a new species thermo manager instance, by specifying
//!the type and (optionally) a pointer to the factory to use to create it.
//! Create a new species thermo manager instance, by specifying the type and
//! (optionally) a pointer to the factory to use to create it.
/*!
* This utility program will look through species nodes. It will discover what
* each species needs for its species property managers. Then,
* it will malloc and return the proper species property manager to use.
*
* These functions allow using a different factory class that
* derives from SpeciesThermoFactory.
* These functions allow using a different factory class that
* derives from SpeciesThermoFactory.
*
* @param type Species thermo type.
* @param f Pointer to a SpeciesThermoFactory. optional parameter.
@ -227,15 +212,15 @@ private:
*/
SpeciesThermo* newSpeciesThermoMgr(int type, SpeciesThermoFactory* f=0);
//! Create a new species thermo manager instance, by specifying
//!the type and (optionally) a pointer to the factory to use to create it.
//! Create a new species thermo manager instance, by specifying the type and
//! (optionally) a pointer to the factory to use to create it.
/*!
* This utility program is a basic factory operation for spawning a
* new species reference-state thermo manager
*
* These functions allows for using a different factory class that
* derives from SpeciesThermoFactory. However, no applications of this
* have been done yet.
* These functions allows for using a different factory class that
* derives from SpeciesThermoFactory. However, no applications of this
* have been done yet.
*
* @param stype String specifying the species thermo type
* @param f Pointer to a SpeciesThermoFactory. optional parameter.
@ -250,14 +235,13 @@ SpeciesThermo* newSpeciesThermoMgr(std::string& stype,
* each species needs for its species property managers. Then,
* it will malloc and return the proper species reference state manager to use.
*
* These functions allow using a different factory class that
* derives from SpeciesThermoFactory.
* These functions allow using a different factory class that
* derives from SpeciesThermoFactory.
*
* @param spDataNodeList This vector contains a list
* of species XML nodes that will be in the phase
*
* @param f Pointer to a SpeciesThermoFactory. optional parameter.
* Defaults to NULL.
* @param spDataNodeList This vector contains a list of species XML nodes that
* will be in the phase
* @param f Pointer to a SpeciesThermoFactory. optional
* parameter. Defaults to NULL.
*/
SpeciesThermo* newSpeciesThermoMgr(std::vector<XML_Node*> spDataNodeList,
SpeciesThermoFactory* f=0);

View file

@ -141,22 +141,19 @@ inline ThermoPhase* newThermoPhase(const std::string& model,
*/
std::string eosTypeString(int ieos, int length = 100);
//! Create a new ThermoPhase object and initializes it according to the XML
//! tree.
/*!
* This routine first looks up the
* identity of the model for the solution thermodynamics in the
* model attribute of the thermo child of the xml phase
* node. Then, it does a string lookup using Cantera's internal ThermoPhase Factory routines
* on the model to figure out
* what ThermoPhase derived class should be assigned. It creates a new
* instance of that class, and then calls importPhase() to
* populate that class with the correct parameters from the XML
* tree.
* This routine first looks up the identity of the model for the solution
* thermodynamics in the model attribute of the thermo child of the xml phase
* node. Then, it does a string lookup using Cantera's internal ThermoPhase
* Factory routines on the model to figure out what ThermoPhase derived class
* should be assigned. It creates a new instance of that class, and then calls
* importPhase() to populate that class with the correct parameters from the
* XML tree.
*
* @param phase XML_Node reference pointing to the phase XML element.
*
* @return
* Returns a pointer to the completed and initialized ThermoPhase object.
* @return A pointer to the completed and initialized ThermoPhase object.
*
* @ingroup inputfiles
*/

View file

@ -120,12 +120,6 @@ SpeciesThermoFactory* SpeciesThermoFactory::factory()
return s_factory;
}
// Delete static instance of this class
/*
* If it is necessary to explicitly delete the factory before
* the process terminates (for example, when checking for
* memory leaks) then this method can be called to delete it.
*/
void SpeciesThermoFactory::deleteFactory()
{
ScopedLock lock(species_thermo_mutex);
@ -135,21 +129,10 @@ void SpeciesThermoFactory::deleteFactory()
}
}
// Destructor
/*
* Doesn't do anything. We do not delete statically
* created single instance of this class here, because it would
* create an infinite loop if destructor is called for that
* single instance.
*/
SpeciesThermoFactory::~SpeciesThermoFactory()
{
}
/*
* Return a species thermo manager to handle the parameterizations
* specified in a CTML phase specification.
*/
SpeciesThermo* SpeciesThermoFactory::newSpeciesThermo(std::vector<XML_Node*> & spDataNodeList) const
{
int inasa = 0, ishomate = 0, isimple = 0, iother = 0;
@ -215,10 +198,6 @@ SpeciesThermo* SpeciesThermoFactory::newSpeciesThermoManager(std::string& stype)
return (SpeciesThermo*) 0;
}
/*
* Check the continuity of properties at the midpoint
* temperature.
*/
void NasaThermo::checkContinuity(const std::string& name, double tmid,
const doublereal* clow, doublereal* chigh)
{
@ -733,19 +712,6 @@ static void installAdsorbateThermoFromXML(const std::string& speciesName,
(&sp)->install(speciesName, k, ADSORBATE, &coeffs[0], tmin, tmax, pref);
}
//================================================================================================
// Install a species thermodynamic property parameterization
// for the reference state for one species into a species thermo manager.
/*
* @param k Species number
* @param speciesNode Reference to the XML node specifying the species standard
* state information
* @param th_ptr Pointer to the %ThermoPhase object for the species
* @param spthermo Species reference state thermo manager
* @param phaseNode_ptr Optional pointer to the XML phase
* information for the phase in which the species
* resides
*/
void SpeciesThermoFactory::installThermoForSpecies
(size_t k, const XML_Node& speciesNode, ThermoPhase* th_ptr,
SpeciesThermo& spthermo, const XML_Node* phaseNode_ptr) const
@ -832,27 +798,7 @@ void SpeciesThermoFactory::installThermoForSpecies
}
}
}
//================================================================================================
// Install a species thermodynamic property parameterization
// for the standard state for one species into a species thermo manager, VPSSMgr
/*
* This is a wrapper around the createInstallVPSS() function in the
* VPStandardStateTP object.
*
* This serves to install the species into vpss_ptr, create a PDSS file. We also
* read the xml database to extract the constants for these steps.
*
* @param k species number
* @param speciesNode Reference to the XML node specifying the species standard
* state information
* @param vp_ptr variable pressure ThermoPhase object
* @param vpss_ptr Pointer to the Manager for calculating variable pressure
* substances.
* @param spthermo_ptr Species reference state thermo manager
* @param phaseNode_ptr Optional Pointer to the XML phase
* information for the phase in which the species
* resides
*/
void SpeciesThermoFactory::
installVPThermoForSpecies(size_t k, const XML_Node& speciesNode,
VPStandardStateTP* vp_ptr,
@ -872,20 +818,6 @@ installVPThermoForSpecies(size_t k, const XML_Node& speciesNode,
vp_ptr->createInstallPDSS(k, speciesNode, phaseNode_ptr);
}
// Create a new species thermo manager instance, by specifying
// the type and (optionally) a pointer to the factory to use to create it.
/*
* This utility program will look through species nodes. It will discover what
* each species needs for its species property managers. Then,
* it will malloc and return the proper species property manager to use.
*
* These functions allow using a different factory class that
* derives from SpeciesThermoFactory.
*
* @param type Species thermo type.
* @param f Pointer to a SpeciesThermoFactory. optional parameter.
* Defaults to NULL.
*/
SpeciesThermo* newSpeciesThermoMgr(int type, SpeciesThermoFactory* f)
{
if (f == 0) {
@ -894,20 +826,6 @@ SpeciesThermo* newSpeciesThermoMgr(int type, SpeciesThermoFactory* f)
return f->newSpeciesThermo(type);
}
// Create a new species thermo manager instance, by specifying
//the type and (optionally) a pointer to the factory to use to create it.
/*
* This utility program is a basic factory operation for spawning a
* new species reference-state thermo manager
*
* These functions allows for using a different factory class that
* derives from SpeciesThermoFactory. However, no applications of this
* have been done yet.
*
* @param stype String specifying the species thermo type
* @param f Pointer to a SpeciesThermoFactory. optional parameter.
* Defaults to NULL.
*/
SpeciesThermo* newSpeciesThermoMgr(std::string& stype,
SpeciesThermoFactory* f)
{
@ -917,22 +835,6 @@ SpeciesThermo* newSpeciesThermoMgr(std::string& stype,
return f->newSpeciesThermoManager(stype);
}
// Function to return SpeciesThermo manager
/*
* This utility program will look through species nodes. It will discover what
* each species needs for its species property managers. Then,
* it will malloc and return the proper species property manager to use.
*
* These functions allow using a different factory class that
* derives from SpeciesThermoFactory.
*
* @param spData_nodes Vector of XML_Nodes, each of which is a speciesData XML Node.
* Each %speciesData node contains a list of XML species elements
* e.g., \<speciesData id="Species_Data"\>
* @param f Pointer to a SpeciesThermoFactory. optional parameter.
* Defaults to NULL.
* @param opt Boolean defaults to false.
*/
SpeciesThermo* newSpeciesThermoMgr(std::vector<XML_Node*> spData_nodes,
SpeciesThermoFactory* f)
{

View file

@ -89,9 +89,6 @@ static int _itypes[] = {cIdealGas, cIncompressible,
cMolarityIonicVPSSTP, cMixedSolventElectrolyte, cRedlichKisterVPSSTP
};
/*
* This method returns a new instance of a subclass of ThermoPhase
*/
ThermoPhase* ThermoFactory::newThermoPhase(const std::string& model)
{
@ -213,14 +210,6 @@ ThermoPhase* ThermoFactory::newThermoPhase(const std::string& model)
return th;
}
// Translate the eosType id into a string
/*
* Returns a string representation of the eosType id for a phase.
* @param ieos eosType id of the phase. This is unique for the phase
* @param length maximum length of the return string. Defaults to 100
*
* @return returns a string representation.
*/
std::string eosTypeString(int ieos, int length)
{
std::string ss = "UnknownPhaseType";
@ -234,18 +223,6 @@ std::string eosTypeString(int ieos, int length)
return ss;
}
/*
* Create a new ThermoPhase object and initializes it according to
* the XML tree database. This routine first looks up the
* identity of the model for the solution thermodynamics in the
* model attribute of the thermo child of the xml phase
* node. Then, it does a string lookup on the model to figure out
* what ThermoPhase derived class is assigned. It creates a new
* instance of that class, and then calls importPhase() to
* populate that class with the correct parameters from the XML
* tree.
*/
ThermoPhase* newPhase(XML_Node& xmlphase)
{
const XML_Node& th = xmlphase.child("thermo");
@ -288,17 +265,15 @@ ThermoPhase* newPhase(const std::string& infile, std::string id)
//====================================================================================================================
//! Gather a vector of pointers to XML_Nodes for a phase
/*!
*
* @param spDataNodeList Output vector of pointer to XML_Nodes which contain the species XML_Nodes for the
* species in the current phase.
* @param spNamesList Output Vector of strings, which contain the names of the species in the phase
* @param spRuleList Output Vector of ints, which contain the value of sprule for each species in the phase
* @param spArray_names Vector of pointers to the XML_Nodes which contains the names of the
* species in the phase
*
* @param spArray_dbases Input vector of pointers to species data bases.
* We search each data base for the required species names
* @param sprule Input vector of sprule values
* @param spDataNodeList Output vector of pointer to XML_Nodes which contain the species XML_Nodes for the
* species in the current phase.
* @param spNamesList Output Vector of strings, which contain the names of the species in the phase
* @param spRuleList Output Vector of ints, which contain the value of sprule for each species in the phase
* @param spArray_names Vector of pointers to the XML_Nodes which contains the names of the
* species in the phase
* @param spArray_dbases Input vector of pointers to species data bases.
* We search each data base for the required species names
* @param sprule Input vector of sprule values
*/
static void formSpeciesXMLNodeList(std::vector<XML_Node*> &spDataNodeList,
std::vector<std::string> &spNamesList,
@ -409,32 +384,7 @@ static void formSpeciesXMLNodeList(std::vector<XML_Node*> &spDataNodeList,
}
}
}
//====================================================================================================================
/*
* Import a phase specification.
* Here we read an XML description of the phase.
* We import descriptions of the elements that make up the
* species in a phase.
* We import information about the species, including their
* reference state thermodynamic polynomials. We then freeze
* the state of the species, and finally call initThermoXML(phase, id)
* a member function of the ThermoPhase object to "finish"
* the description.
*
*
* @param phase This object must be the phase node of a
* complete XML tree
* description of the phase, including all of the
* species data. In other words while "phase" must
* point to an XML phase object, it must have
* sibling nodes "speciesData" that describe
* the species in the phase.
* @param th Pointer to the ThermoPhase object which will
* handle the thermodynamics for this phase.
* We initialize part of the Thermophase object
* here, especially for those objects which are
* part of the Cantera Kernel.
*/
bool importPhase(XML_Node& phase, ThermoPhase* th,
SpeciesThermoFactory* spfactory)
{
@ -660,53 +610,12 @@ bool importPhase(XML_Node& phase, ThermoPhase* th,
return true;
}
/*
* Install a species into a ThermoPhase object, which defines
* the phase thermodynamics and speciation.
*
* This routine first gathers the information from the Species XML
* tree and calls addUniqueSpecies() to add it to the
* ThermoPhase object, p.
* This information consists of:
* ecomp[] = element composition of species.
* chgr = electric charge of species
* name = string name of species
* sz = size of the species
* (option double used a lot in thermo)
*
* Then, the routine processes the "thermo" XML element and
* calls underlying utility routines to read the XML elements
* containing the thermodynamic information for the reference
* state of the species. Failures or lack of information trigger
* an "UnknownSpeciesThermoModel" exception being thrown.
* *
* @param k Species Index in the phase
* @param s XML_Node containing the species data for this species.
* @param p Reference to the ThermoPhase object.
* @param spthermo Reference to the SpeciesThermo object, where
* the standard state thermo properties for this
* species will be installed.
* @param rule Parameter that handles what to do with species
* who have elements that aren't declared.
* Check that all elements in the species
* exist in 'p'. If rule != 0, quietly skip
* this species if some elements are undeclared;
* otherwise, throw an exception
* @param phaseNode_ptr Pointer to the XML_Node for this phase
* (defaults to 0)
* @param factory Pointer to the SpeciesThermoFactory .
* (defaults to 0)
*
* @return
* Returns true if everything is ok, false otherwise.
*/
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)
{
std::string xname = s.name();
if (xname != "species") {
throw CanteraError("installSpecies",
@ -779,19 +688,6 @@ bool installSpecies(size_t k, const XML_Node& s, thermo_t& th,
return true;
}
// Search an XML tree for species data.
/*
* This utility routine will search the XML tree for the species
* named by the string, kname. It will return the XML_Node
* pointer to the species data for that species.
* Failures of any kind return the null pointer.
*
* @param kname String containing the name of the species.
* @param phaseSpeciesData Pointer to the XML speciesData element
* containing the species data for that phase.
*
*/
const XML_Node* speciesXML_Node(const std::string& kname,
const XML_Node* phaseSpeciesData)
{

View file

@ -43,13 +43,12 @@ namespace Cantera
VPSSMgrFactory* VPSSMgrFactory::s_factory = 0;
// Defn of the static mutex variable that locks the %VPSSMgr factory singleton
// Defn of the static mutex variable that locks the VPSSMgr factory singleton
mutex_t VPSSMgrFactory::vpss_species_thermo_mutex;
//! Examine the types of species thermo parameterizations, and return a flag indicating the type of parameterization
//! needed by the species.
/*!
*
* @param spDataNodeList Species Data XML node. This node contains a list
* of species XML nodes underneath it.
* @param has_nasa_idealGas Boolean indicating that one species has a NASA ideal gas standard state
@ -187,12 +186,6 @@ static void getVPSSMgrTypes(std::vector<XML_Node*> & spDataNodeList,
}
}
// Delete static instance of this class
/*
* If it is necessary to explicitly delete the factory before
* the process terminates (for example, when checking for
* memory leaks) then this method can be called to delete it.
*/
void VPSSMgrFactory::deleteFactory()
{
ScopedLock lock(vpss_species_thermo_mutex);
@ -229,8 +222,6 @@ VPSSMgrFactory::VPSSMgr_StringConversion(const std::string& ssModel) const
return type;
}
// Chose the variable pressure standard state manager
// and the reference standard state manager
VPSSMgr*
VPSSMgrFactory::newVPSSMgr(VPStandardStateTP* vp_ptr,
XML_Node* phaseNode_ptr,
@ -321,8 +312,6 @@ VPSSMgrFactory::newVPSSMgr(VPStandardStateTP* vp_ptr,
return new VPSSMgr_General(vp_ptr, spth);
}
// I don't think this is currently used. However, this is a virtual
// function where additional capabilities may be added.
VPSSMgr*
@ -372,5 +361,4 @@ VPSSMgr* newVPSSMgr(VPStandardStateTP* tp_ptr,
return f->newVPSSMgr(tp_ptr, phaseNode_ptr, spDataNodeList);
}
}

View file

@ -27,7 +27,6 @@ class VPStandardStateTP;
//! Throw a named error for an unknown or missing vpss species thermo model.
/*!
*
* @ingroup mgrpdssthermocalc
*/
class UnknownVPSSMgrModel: public CanteraError
@ -105,10 +104,9 @@ public:
//! Destructor
/*!
* Doesn't do anything. We do not delete statically
* created single instance of this class here, because it would
* create an infinite loop if destructor is called for that
* single instance.
* Doesn't do anything. We do not delete statically created single
* instance of this class here, because it would create an infinite loop
* if destructor is called for that single instance.
*/
virtual ~VPSSMgrFactory();
@ -151,7 +149,6 @@ public:
std::vector<XML_Node*> & spDataNodeList);
private:
//! pointer to the sole instance of this class
static VPSSMgrFactory* s_factory;
@ -176,9 +173,9 @@ private:
//! Create a new species thermo manager instance, by specifying
//! the type and (optionally) a pointer to the factory to use to create it.
/*!
* This utility program will look through species nodes. It will discover what
* each species needs for its species property managers. Then,
* it will malloc and return the proper species property manager to use.
* This utility program will look through species nodes. It will discover what
* each species needs for its species property managers. Then, it will malloc
* and return the proper species property manager to use.
*
* These functions allow using a different factory class that
* derives from SpeciesThermoFactory.
@ -194,22 +191,20 @@ VPSSMgr* newVPSSMgr(VPSSMgr_enumType type,
//! Function to return VPSSMgr manager
/*!
* This utility program will look through species nodes. It will discover what
* each species needs for its species property managers. Then,
* it will alloc and return the proper species property manager to use.
* This utility program will look through species nodes. It will discover what
* each species needs for its species property managers. Then, it will alloc
* and return the proper species property manager to use.
*
* These functions allow using a different factory class that
* derives from SpeciesThermoFactory.
*
* @param vp_ptr Variable pressure standard state ThermoPhase object
* that will be the owner.
* @param vp_ptr Variable pressure standard state ThermoPhase object
* that will be the owner.
* @param phaseNode_ptr Pointer to the ThermoPhase phase XML Node
*
* @param spDataNodeList This vector contains a list
* of species XML nodes that will be in the phase
*
* @param f Pointer to a SpeciesThermoFactory. optional parameter.
* Defaults to NULL.
* @param f Pointer to a SpeciesThermoFactory. optional
* parameter. Defaults to NULL.
*/
VPSSMgr* newVPSSMgr(VPStandardStateTP* vp_ptr,
XML_Node* phaseNode_ptr,
@ -219,5 +214,3 @@ VPSSMgr* newVPSSMgr(VPStandardStateTP* vp_ptr,
}
#endif