diff --git a/Cantera/src/Constituents.h b/Cantera/src/Constituents.h index d7a14a908..485b82633 100755 --- a/Cantera/src/Constituents.h +++ b/Cantera/src/Constituents.h @@ -1,7 +1,8 @@ - -/// @file Constituents.h -/// Header file for class Constituents - +/*! + * @file Constituents.h + * + * Header file for class Constituents + */ /* $Author$ * $Date$ @@ -28,21 +29,33 @@ namespace Cantera { class Elements; - /************** DEFINITIONS OF ERRORS *****************************/ + //! Specific fatal error indicating that the index of a species is out of range. + /*! + * + * @ingroup errorhandling + */ class SpeciesRangeError : public CanteraError { public: - SpeciesRangeError(std::string func, int k, int kmax) : - CanteraError(func, "Species index " + int2str(k) + - " outside valid range of 0 to " + int2str(kmax-1)) {} + //! Constructor + /*! + * @param func Function where the error occurred. + * @param k current species index value + * @param kmax Maximum permissible species index value. The + * minimum permissible species index value is assumed to be 0 + * + */ + SpeciesRangeError(std::string func, int k, int kmax) : + CanteraError(func, "Species index " + int2str(k) + + " outside valid range of 0 to " + int2str(kmax-1)) {} }; /******************************************************************/ - /// Class Constituents manages a set of elements and - /// species. Class Constituents is designed to provide information + /// Class %Constituents manages a set of elements and + /// species. Class %Constituents is designed to provide information /// about the elements and species in a phase - names, index /// numbers (location in arrays), atomic or molecular weights, /// etc. No computations are performed by the methods of this @@ -223,25 +236,46 @@ namespace Cantera { protected: - int m_kk; - vector_fp m_weight; + //! Number of species in the phase. + int m_kk; + //! Vector of molecular weights of the species + /*! + * This vector has length m_kk. + * The units of the vector are kg kmol-1. + */ + vector_fp m_weight; - bool m_speciesFrozen; + //! Boolean indicating whether the number of species has been frozen. + /*! + * During the construction of the phase, this is false. After + * construction of the the phase, this is true. + */ + bool m_speciesFrozen; - /* + /*! * Pointer to the element object corresponding to this * phase. Normally, this will be the default Element object * common to all phases. */ Elements * m_Elements; - std::vector m_speciesNames; - vector_fp m_speciesComp; + //! Vector of the species names + std::vector m_speciesNames; + + //! Atomic composition of the species. + /*! + * the number of atoms of i in species k is equal to + * m_speciesComp[k * m_mm + i] + * The length of this vector is equal to m_kk * m_mm + */ + vector_fp m_speciesComp; + /** * m_speciesCharge: Vector of species charges * length = m_kk */ vector_fp m_speciesCharge; + /** * m_speciesSize(): Vector of species sizes. * length m_kk diff --git a/Cantera/src/GasKineticsWriter.h b/Cantera/src/GasKineticsWriter.h index 05967b104..070cdec16 100755 --- a/Cantera/src/GasKineticsWriter.h +++ b/Cantera/src/GasKineticsWriter.h @@ -36,11 +36,10 @@ namespace Cantera { class Enhanced3BConc; class ReactionData; - /** - * Class to write a hard-coded version of a mechanism. - * @ingroup kineticsGroup + //! Class to write a hard-coded version of a mechanism. + /*! + * @ingroup kineticsmgr */ - class GasKineticsWriter { public: diff --git a/Cantera/src/Kinetics.h b/Cantera/src/Kinetics.h index e2ae8216a..31be27e88 100755 --- a/Cantera/src/Kinetics.h +++ b/Cantera/src/Kinetics.h @@ -1,5 +1,9 @@ /** * @file Kinetics.h + * + * Base class for kinetics managers + * + * Contains the kineticsmgr module documentation. * * $Author$ * $Date$ @@ -8,10 +12,6 @@ // Copyright 2001-2004 California Institute of Technology -/** - * @defgroup kineticsGroup Kinetics - */ - #ifndef CT_KINETICS_H #define CT_KINETICS_H @@ -109,22 +109,24 @@ namespace Cantera { /// 5 locations. - /// Public interface for kinetics managers. This class serves as a - /// base class to derive 'kinetics managers', which are classes - /// that manage homogeneous chemistry within one phase, or - /// heterogeneous chemistry at one interface. The virtual methods - /// of this class are meant to be overloaded in subclasses. The - /// non-virtual methods perform generic functions and are - /// implemented in Kinetics. They should not be overloaded. Only - /// those methods required by a subclass need to be overloaded; - /// the rest will throw exceptions if called. @ingroup kinetics - /// @ingroup kineticsmgr - + //! Public interface for kinetics managers. + /*! + * This class serves as a + * base class to derive 'kinetics managers', which are classes + * that manage homogeneous chemistry within one phase, or + * heterogeneous chemistry at one interface. The virtual methods + * of this class are meant to be overloaded in subclasses. The + * non-virtual methods perform generic functions and are + * implemented in Kinetics. They should not be overloaded. Only + * those methods required by a subclass need to be overloaded; + * the rest will throw exceptions if called. @ingroup kinetics + * @ingroup kineticsmgr + */ class Kinetics { public: - // typedefs + //! typedef for ThermoPhase typedef ThermoPhase thermo_t; /** @@ -727,6 +729,7 @@ namespace Cantera { /// For internal use. May be removed in a future release. int index(){ return m_index; } + //! Set the index of the Kinetics Manager void setIndex(int index) { m_index = index; } @@ -796,6 +799,7 @@ namespace Cantera { * -1. */ std::map m_phaseindex; + //! Index of the Kinetics Manager int m_index; /** @@ -819,7 +823,7 @@ namespace Cantera { }; - + //! typedef for the kinetics base class typedef Kinetics kinetics_t; } diff --git a/Cantera/src/Phase.h b/Cantera/src/Phase.h index e71fb3e7d..bac26e862 100755 --- a/Cantera/src/Phase.h +++ b/Cantera/src/Phase.h @@ -62,14 +62,28 @@ namespace Cantera { */ const Phase &operator=(const Phase &c); + //! Returns a reference to the XML_Node storred for the phase + /*! + * The XML_Node for the phase contains all of the input data used + * to set up the model for the phase, during its initialization. + */ XML_Node& xml() { return *m_xml; } + + //! Return the string id for the phase std::string id() const { return m_id; } + + //! Set the string id for the phase void setID(std::string id) {m_id = id;} + //! Return the name of the phase std::string name() const { return m_name; } + + //! Sets the string name for the phase void setName(std::string nm) { m_name = nm; } + //! Returns the index of the phase int index() const { return m_index; } + //! Sets the index of the phase void setIndex(int m) { m_index = m; } /** @@ -92,6 +106,11 @@ namespace Cantera { */ void restoreState(const vector_fp& state); + //! Restore the state of the phase from a previously saved state vector. + /*! + * @param lenstate Length of the state vector + * @param state Vector of state conditions. + */ void restoreState(int lenstate, const doublereal* state); /** @@ -101,6 +120,14 @@ namespace Cantera { */ void setMoleFractionsByName(compositionMap& xMap); + //! Set the mole fractions of a group of species by name + /*! + * The string x is in the form of a composition map + * Species which are not listed by name in the composition + * map are set to zero. + * + * @param x string x in the form of a composition map + */ void setMoleFractionsByName(const std::string& x); /** @@ -110,6 +137,13 @@ namespace Cantera { */ void setMassFractionsByName(compositionMap& yMap); + + //! Set the species mass fractions by name. + /*! + * Species not listed by name in \c x are set to zero. + * + * @param x String containing a composition map + */ void setMassFractionsByName(const std::string& x); /** Set the temperature (K), density (kg/m^3), and mole fractions. */ @@ -168,12 +202,36 @@ namespace Cantera { */ void getMoleFractionsByName(compositionMap& x); + //! Return the mole fraction of a single species + /*! + * @param k String name of the species + * + * @return Mole fraction of the species + */ doublereal moleFraction(int k) const; + //! Return the mole fraction of a single species + /*! + * @param name String name of the species + * + * @return Mole fraction of the species + */ doublereal moleFraction(std::string name) const; + //! Return the mass fraction of a single species + /*! + * @param k String name of the species + * + * @return Mass Fraction of the species + */ doublereal massFraction(int k) const; + //! Return the mass fraction of a single species + /*! + * @param name String name of the species + * + * @return Mass Fraction of the species + */ doublereal massFraction(std::string name) const; /** @@ -183,6 +241,12 @@ namespace Cantera { /// Number of spatial dimensions (1, 2, or 3) int nDim() {return m_ndim;} + + //! Set the number of spatial dimensions (1, 2, or 3) + /*! + * The number of spatial dimensions is used for vector involving + * directions. + */ void setNDim(int ndim) {m_ndim = ndim;} /** @@ -224,6 +288,7 @@ namespace Cantera { std::string m_name; }; + //! typedef for the base Phase class typedef Phase phase_t; } diff --git a/Cantera/src/State.h b/Cantera/src/State.h index c7a042a5f..dd3ddc968 100755 --- a/Cantera/src/State.h +++ b/Cantera/src/State.h @@ -281,6 +281,11 @@ namespace Cantera { */ int m_kk; + //! Set the molecular weight of a single species to a given value + /*! + * @param k id of the species + * @param mw Molecular Weight (kg kmol-1) + */ void setMolecularWeight(int k, double mw) { m_molwts[k] = mw; m_rmolwts[k] = 1.0/mw; diff --git a/Cantera/src/ThermoPhase.h b/Cantera/src/ThermoPhase.h index adcaa13b8..106dece94 100755 --- a/Cantera/src/ThermoPhase.h +++ b/Cantera/src/ThermoPhase.h @@ -22,10 +22,16 @@ namespace Cantera { - const int cAC_CONVENTION_MOLAR = 0; - const int cAC_CONVENTION_MOLALITY = 1; - - class XML_Node; + /*! + * @name CONSTANTS - Specification of the Molality conventention + */ + //@{ + //! Standard state uses the molar convention + const int cAC_CONVENTION_MOLAR = 0; + //! Stanadrd state uses the molality convention + const int cAC_CONVENTION_MOLALITY = 1; + //@} + class XML_Node; /** @@ -269,12 +275,19 @@ namespace Cantera { * This is used by classes InterfaceKinetics and EdgeKinetics to * compute the rates of charge-transfer reactions, and in computing * the electrochemical potentials of the species. + * + * Each phase may have its own electric potential. + * + * ¶m v Value of the electric potential in Volts */ void setElectricPotential(doublereal v) { m_phi = v; } - /// The electric potential of this phase (V). + //! Returns the electric potential of this phase (V). + /*! + * Units are Volts + */ doublereal electricPotential() const { return m_phi; } /** @@ -675,6 +688,10 @@ namespace Cantera { } //@} + //! Return the Gas Constant multiplied by the current temperature + /*! + * The units are Joules kmol-1 + */ doublereal _RT() const { return temperature() * GasConstant; } @@ -1027,10 +1044,15 @@ namespace Cantera { /// Index number int m_index; + //! Storred value of the electric potential for this phase + /*! + * Units are Volts + */ doublereal m_phi; /// Vector of element potentials. /// -> length equal to number of elements vector_fp m_lambdaRRT; + //! Boolean indicating whether there is a valid set of saved element potentials for this phase bool m_hasElementPotentials; private: @@ -1039,7 +1061,9 @@ namespace Cantera { }; + //! typedef for the ThermoPhase class typedef ThermoPhase thermophase_t; + //! typedef for the ThermoPhase class typedef ThermoPhase thermo_t; } diff --git a/Cantera/src/ct_defs.h b/Cantera/src/ct_defs.h index 5fcceba65..aa77fbf95 100755 --- a/Cantera/src/ct_defs.h +++ b/Cantera/src/ct_defs.h @@ -3,7 +3,11 @@ * @file ct_defs.h * * This file contains definitions of terms that are used in internal - * routines and are unlikely to need modifying + * routines and are unlikely to need modifying. This file is included + * into every file that is in the Cantera Namespace. + * + * All physical constants are storred here. + * The module physConstants is defined here. */ /* $Author$ @@ -28,17 +32,15 @@ #include #include -//using namespace std; - -//#include "ctvector.h" -//using namespace ct; +//! creates a pointer to the start of the raw data for a ctvector #define DATA_PTR(vec) &vec[0] #ifdef WIN32 #define TYPENAME_KEYWORD #pragma warning(disable:4267) #else +//! create a define for the typename command #define TYPENAME_KEYWORD typename #endif @@ -49,16 +51,27 @@ */ namespace Cantera { + /*! + * All physical constants are storred here. + * + * @defgroup physConstants Physical Constants + * %Cantera uses the MKS system of units. The unit for moles + * is defined to be the kmol. + * @ingroup globalData + * @{ + */ + //! Pi const doublereal Pi = 3.1415926; + //! sqrt(Pi) const doublereal SqrtPi = std::sqrt(Pi); - // use kg-moles, rather than g-moles. - // Note: this constant is a relic of old versions, - // and appears to be no longer used anywhere. - const doublereal CtMoles_per_mole = 1.e-3; // kmol - - /// @name Physical Constants - //@{ + + /*! + * @name Variations of the Gas Constant + * %Cantera uses the MKS system of units. The unit for moles + * is defined to be the kmol. + */ + //@{ /// Avogadro's Number const doublereal Avogadro = 6.022136736e26; @@ -79,7 +92,7 @@ namespace Cantera { /// Boltzmann's constant const doublereal Boltzmann = GasConstant / Avogadro; - /// Planck's constant + /// Planck's constant. Units of J-s const doublereal Planck = 6.626068e-34; // J-s const doublereal Planck_bar = 1.05457148e-34; // m2-kg/s @@ -88,6 +101,7 @@ namespace Cantera { /// Stefan-Boltzmann constant const doublereal StefanBoltz = 5.67e-8; + //@} /// @name Electron Properties //@{ const doublereal ElectronCharge = 1.602e-19; // C @@ -96,7 +110,7 @@ namespace Cantera { //@} /// @name Electromagnetism - /// Cantera uses the MKS unit system. + /// %Cantera uses the MKS unit system. //@{ /// Permittivity of free space \f$ \epsilon_0 \f$ in F/m. @@ -106,59 +120,65 @@ namespace Cantera { const doublereal permeability_0 = 4.0e-7*Pi; // N/A^2 //@} - - //@} - - const doublereal OneThird = 1.0/3.0; - const doublereal FiveSixteenths = 5.0/16.0; - const doublereal SqrtTen = std::sqrt(10.0); - const doublereal SqrtEight = std::sqrt(8.0); - - const doublereal SmallNumber = 1.e-300; - const doublereal BigNumber = 1.e300; - - /// largest x such that exp(x) is valid - const doublereal MaxExp = 690.775527898; - - const int Undefined = -999; - const doublereal Undef = -999.1234; - const doublereal Cutoff = 1.e-12; - const doublereal Tiny = 1.e-20; - - + //@} + + /*! + * @name Thermodynamic Equilibrium Constraints + * Integer numbers representing pairs of thermodynamic variables + * which are held constant during equilibration. + */ + //@{ const int TV = 100, HP = 101, SP = 102, PV = 103, TP = 104, UV = 105, ST = 106, SV = 107, UP = 108, VH = 109, TH = 110, SH = 111, PX = 112, TX = 113; const int VT = -100, PH = -101, PS = -102, VP = -103, PT = -104, VU = -105, TS = -106, VS = -107, PU = -108, HV = -109, HT = -110, HS = -111, XP = -112, XT = -113; + //@} + //! 1/3 + const doublereal OneThird = 1.0/3.0; + //! 5/16 + const doublereal FiveSixteenths = 5.0/16.0; + //! sqrt(10) + const doublereal SqrtTen = std::sqrt(10.0); + //! sqrt(8) + const doublereal SqrtEight = std::sqrt(8.0); + //! smallest number to compare to zero. + const doublereal SmallNumber = 1.e-300; + //! largest number to compare to inf. + const doublereal BigNumber = 1.e300; + //! largest x such that exp(x) is valid + const doublereal MaxExp = 690.775527898; + + //! Fairly random number to be used to initialize variables against to see if they are subsequently defined. + const doublereal Undef = -999.1234; + //! Small number to compare differences of mole fractions against. + const doublereal Tiny = 1.e-20; + //! inline function to return the max value of two doubles. inline doublereal fmaxx(doublereal x, doublereal y) { return (x > y) ? x : y; } + //! inline function to return the min value of two doubles. inline doublereal fminn(doublereal x, doublereal y) { return (x < y) ? x : y; } - const int GAS = 0; - const int LIQUID = 1; - const int SOLID = 2; - const int PURE_FLUID = 3; - // enum Phase {GAS, LIQUID, SOLID, PURE_FLUID}; - - const int Solid_Phase = 0, - Liquid_Phase = 1, - Vapor_Phase = 2, - Gas_Phase = 2; - - const int None = 0; - - // typedefs + //! Map connecting a string name with a double. + /*! + * This is used mostly to assign concentrations and mole fractions + * to species. + */ typedef std::map compositionMap; +//! Turn on the use of stl vectors for the basic array type within cantera #define USE_STL_VECTOR #ifdef USE_STL_VECTOR - typedef std::vector array_fp; - typedef std::vector vector_fp; + //! Vector of doubles. + typedef std::vector array_fp; + //! Vector of doubles. + typedef std::vector vector_fp; + //! Vector of ints typedef std::vector array_int; + //! Vector of ints typedef std::vector vector_int; #else typedef ct::ctvector_fp array_fp; @@ -166,19 +186,23 @@ namespace Cantera { typedef ct::ctvector_int array_int; typedef ct::ctvector_int vector_int; #endif + //! typedef for a group of species. + /*! + * A group of species is a subset of the species in a phase. + */ typedef vector_int group_t; - typedef std::vector grouplist_t; + //! typedef for a vector of groups of species. + /*! + * A grouplist of species is a vector of groups. + */ + typedef std::vector grouplist_t; + //! Typedef for a pointer to temporary work storage typedef doublereal* workPtr; + //! typedef for a pointer to temporary work storage which is treated as constant typedef const doublereal* const_workPtr; - // template - //inline doublereal operator*(const vector& u, const vector& v) { - // return std::inner_product(u.begin(), u.end(), v.begin(), 0.0); - // } - - } // namespace #endif diff --git a/Cantera/src/ctml.cpp b/Cantera/src/ctml.cpp index ede193d23..728d4ff50 100755 --- a/Cantera/src/ctml.cpp +++ b/Cantera/src/ctml.cpp @@ -276,8 +276,8 @@ namespace ctml { int x, x0, x1; string units, vmin, vmax; x = atoi(node().c_str()); - x0 = Undefined; - x1 = Undefined; + x0 = -9999999; + x1 = 9999999; vmin = node["min"]; vmax = node["max"]; if (vmin != "") { diff --git a/Cantera/src/global.h b/Cantera/src/global.h index bf6789ffb..f9c5f1e0a 100755 --- a/Cantera/src/global.h +++ b/Cantera/src/global.h @@ -1,10 +1,14 @@ /** * @file global.h * - * These functions handle various utility functions, and store - * some parameters in - * global storage that are accessible at all times. - * + * This file contains definitions for utility functions. These functions store + * some parameters in global storage that are accessible at all times + * from the calling application. + * Contains module definitions for + * inputfiles + * logs + * textlogs + * HTML_logs */ /* $Author$ @@ -17,7 +21,6 @@ #ifndef CT_GLOBAL_H #define CT_GLOBAL_H -#include #include "ct_defs.h" namespace Cantera { @@ -48,7 +51,7 @@ namespace Cantera { * @param r Procedure name which is generating the error condition * @param msg Descriptive message of the error condition. * - * \ingroup errorhandling + * @ingroup errorhandling */ void setError(std::string r, std::string msg); @@ -81,7 +84,7 @@ namespace Cantera { //! Discard the last error message /*! - * Cantera saves a stack of exceptions that it + * %Cantera saves a stack of exceptions that it * has caught in the Application class. This routine eliminates * the last exception to be added to that stack. * @@ -89,39 +92,192 @@ namespace Cantera { */ void popError(); - /// Find an input file. - std::string findInputFile(std::string name); + /*! + * @defgroup inputfiles Input File Handling + * + * The properties of phases and interfaces are specified in + * text files. These procedures handle various aspects of reading + * these files. + * + * For input files not specified by an absolute pathname, + * %Cantera searches + * for input files along a path that includes platform-specific + * default locations, and possibly user-specified locations. + * + * The current directory (".") is always searched first. Then, on + * Windows platforms, if environment variable COMMONPROGRAMFILES + * is set (which it should be on Win XP or Win 2000), then + * directories under this one will be added to the search + * path. The %Cantera Windows installer installs data files to this + * location. + * + * On the Mac, directory '/Applications/Cantera/data' is added to the + * search path. + * + * On any platform, if environment variable CANTERA_DATA is set to a + * directory name, then this directory is added to the search path. + * + * Finally, the location where the data files were installed when + * %Cantera was built is added to the search path. + * + * Additional directories may be added by calling function addDirectory. + * @{ + */ - void addDirectory(std::string dir); + //! Find an input file. + /*! + * This routine will search for a file in the default + * locations specified for the application. + * See the routine setDefaultDirectories() listed above. + * + * The default set of directories specified for the application + * will be searched if a '/' or an '\\' is found in the + * name. If either is found then a relative path name is + * presumed, and the default directories are not searched. + * + * The presence of the file is determined by whether the file + * can be opened for reading by the current user. + * + * @param name Name of the input file to be searched for + * + * @return + * + * The absolute path name of the first matching + * file is returned. If a relative path name + * is indicated, the relative path name is returned. + * + * If the file is not found, a message is written to + * stdout and a CanteraError exception is thrown. + * + * @ingroup inputfiles + */ + std::string findInputFile(std::string name); - void appdelete(); + //! Add a directory to the input file search path. + /*! + * @ingroup inputfiles + */ + void addDirectory(std::string dir); - /// The root directory where Cantera is installed - std::string canteraRoot(); + //@} - /// Set the temporary file directory. The default is to use the - /// directory specified by enviroment variable TMP or TEMP. If neither - /// of these are defined, then the current working directory will be - /// used for temporary files. Call this function to specify some other - /// place to put temporary files. - void setTmpDir(std::string tmp); + //! Delete and free all memory associated with the application + /*! + * Delete all global data. It should be called at the end of the + * application if leak checking is to be done. + */ + void appdelete(); - /// The directory where temporary files may be created - std::string tmpDir(); + //! Returns root directory where %Cantera where installed + /*! + * @return + * Returns a string containing the name of the base directory where %Cantera is installed. + * If the environmental variable CANTERA_ROOT is defined, this function will + * return its value, preferentially. + * + * @ingroup inputfiles + */ + std::string canteraRoot(); - /// Delay time in seconds. - std::string sleep(); + //! Sets the temporary file directory. + /*! + * The default is to use the + * directory specified by enviroment variable TMP or TEMP. If neither + * of these are defined, then the current working directory will be + * used for temporary files. Call this function to specify some other + * place to put temporary files. + * + * @ingroup inputfiles + */ + void setTmpDir(std::string tmp); - void writelog(const std::string& msg); + //! Retrieves the directory name where temporary files are created + /*! + * @ingroup inputfiles + * @return + * Returns a string containing the directory name + */ + std::string tmpDir(); - void writelog(const char* msg); + //! Delay time in seconds. + /*! + * @return + * Returns the length of time in seconds for calls to the + * sleep function. + * @ingroup inputfiles + */ + std::string sleep(); - void error(const std::string& msg); + /*! + * @defgroup logs Diagnostic Output + * + * Writing diagnostic information to the screen or to a file. + * It is often useful to be able to write diagnostic messages to + * the screen or to a file. Cantera provides two sets of + * procedures for this purpose. The first set is designed to + * write text messages to the screen to document the progress of + * a complex calculation, such as a flame simulation.The second + * set writes nested lists in HTML format. This is useful to + * print debugging output for a complex calculation that calls + * many different procedures. + */ - // returns 1 for MATLAB, 2 for Python, and 0 for C++ or Fortran. - int userInterface(); + /*! + * @defgroup textlogs Writing messages to the screen + * @ingroup logs + */ - void setLogger(Logger* logwriter); + + //! Write a message to the screen. + /*! + * The string may be of any + * length, and may contain end-of-line characters. This method is + * used throughout Cantera to write log messages. It can also be + * called by user programs. The advantage of using writelog over + * writing directly to the standard output is that messages + * written with writelog will display correctly even when Cantera + * is used from MATLAB or other application that do not have a + * standard output stream. + * + * @param msg String message to be written to the screen + * @ingroup textlogs + */ + void writelog(const std::string& msg); + + //! Write a message to the screen. + /*! + * The string may be of any + * length, and may contain end-of-line characters. This method is + * used throughout %Cantera to write log messages. + * + * @param msg c character string to be written to the screen + * @ingroup textlogs + */ + void writelog(const char* msg); + + //! Write an error message and terminate execution. + /*! + * @param msg Error message to be written to the screen. + * @ingroup textlogs + */ + void error(const std::string& msg); + + //! returns 1 for MATLAB, 2 for Python, and 0 for C++ or Fortran. + /*! + * @ingroup textlogs + */ + int userInterface(); + + //! Install a logger. + /*! + * Called by the language interfaces to install an appropriate logger. + * The logger is used for the writelog() function + * + * @param logwriter Pointer to a logger object + * @see Logger. + * @ingroup textlogs + */ + void setLogger(Logger* logwriter); /// Return the conversion factor to convert unit std::string 'unit' to /// SI units. @@ -138,21 +294,125 @@ namespace Cantera { void close_XML_File(std::string file); #ifdef WITH_HTML_LOGS - void beginLogGroup(std::string title, int loglevel=-99); - void addLogEntry(std::string tag, std::string value); - void addLogEntry(std::string tag, doublereal value); - void addLogEntry(std::string tag, int value); - void addLogEntry(std::string msg); + + /*! + * @defgroup HTML_logs Writing HTML Logfiles + * @ingroup logs + * + * These functions are designed to allow writing HTML diagnostic + * messages in a manner that allows users to control how much + * diagnostic output to print. It works like this: Suppose you + * have function A that invokes function B that invokes function + * C. You want to be able to print diagnostic messages just from + * function A, or from A and B, or from A, B, and C, or to turn + * off printing diagnostic messages altogether. All you need to + * do is call 'beginLogGroup' within function A, and specify a + * loglevel value. Then in B, call beginLogGroup again, but + * without an explicit value for loglevel. By default, the + * current level is decremented by one in beginLogGroup. If it + * is <= 0, no log messages are written. Thus, if each function + * begins with beginLogGroup and calls endLogGroup before + * returning, then setting loglevel = 3 will cause messages from + * A, B, and C to be written (in nested HTML lists), loglevel = + * 2 results in messages only being written from A and B, etc. + */ + + //!Create a new group for log messages. + /*! + * Usually this is called + * upon entering the function, with the title parameter equal to + * the name of the function or method. Subsequent messages + * written with addLogEntry will appear grouped under this + * heading, until endLogGroup() is called. + * + * @param title String name of the LogGroup + * @param loglevel loglevel of the group. + * @ingroup HTML_logs + */ + void beginLogGroup(std::string title, int loglevel=-99); + + //! Add an entry to an HTML log file. + /*! + * Entries appear in the form "tag:value". + * + * @param tag tag + * @param value string value + * + * @ingroup HTML_logs + */ + void addLogEntry(std::string tag, std::string value); + + //! Add an entry to an HTML log file. + /*! + * Entries appear in the form "tag:value". + * + * @param tag tag + * @param value double value + * + * @ingroup HTML_logs + */ + void addLogEntry(std::string tag, doublereal value); + + //! Add an entry to an HTML log file. + /*! + * Entries appear in the form "tag:value". + * + * @param tag tag + * @param value int value + * + * @ingroup HTML_logs + */ + void addLogEntry(std::string tag, int value); + + //! Add an entry msg string to an HTML log file. + /*! + * Add a message string to the HTML log file + * + * @param msg string mesg + * + * @ingroup HTML_logs + */ + void addLogEntry(std::string msg); + + //! Close the current group of log messages. + /*! + * This is typically + * called just before leaving a function or method, to close the + * group of messages that were output from this + * function. Subsequent messages written with addLogEntry() will + * appear at the next-higher level in the outline, unless + * beginLogGroup() is called first to create a new group. + * + * @param title Name of the log group. It defaults to the most recent + * log group created. + * @ingroup HTML_logs + */ void endLogGroup(std::string title=""); - void write_logfile(std::string file = "log.html"); + + //! Write the HTML log file. + /*! + * Log entries are stored in memory in + * an XML tree until this function is called, which writes the + * tree to a file and clears the entries stored in memory. The + * output file will have the name specified in the 'file' + * argument. If this argument has no extension, the extension + * '.html' will be appended. Also, if the file already exists, an + * integer will be appended to the name so that no existing log + * file will be overwritten. will be appended to the name. + * + * @param file Name of the file to be written + * @ingroup HTML_logs + */ + void write_logfile(std::string file = "log.html"); + #else - inline void beginLogGroup(std::string title, int loglevel=-99) {} - inline void addLogEntry(std::string tag, std::string value) {} - inline void addLogEntry(std::string tag, doublereal value) {} - inline void addLogEntry(std::string tag, int value) {} - inline void addLogEntry(std::string msg) {} - inline void endLogGroup(std::string title="") {} - inline void write_logfile(std::string file = "log.html") {} + inline void beginLogGroup(std::string title, int loglevel=-99) {} + inline void addLogEntry(std::string tag, std::string value) {} + inline void addLogEntry(std::string tag, doublereal value) {} + inline void addLogEntry(std::string tag, int value) {} + inline void addLogEntry(std::string msg) {} + inline void endLogGroup(std::string title="") {} + inline void write_logfile(std::string file = "log.html") {} #endif } diff --git a/Cantera/src/logger.h b/Cantera/src/logger.h index b992a47f0..561627c11 100644 --- a/Cantera/src/logger.h +++ b/Cantera/src/logger.h @@ -36,7 +36,9 @@ namespace Cantera { class Logger { public: + //! Constructor - empty Logger() {} + //! Destructor - empty virtual ~Logger() {} /// Write a log message. The default behavior is to write to diff --git a/Cantera/src/misc.cpp b/Cantera/src/misc.cpp index d5c14b978..513f24ee4 100755 --- a/Cantera/src/misc.cpp +++ b/Cantera/src/misc.cpp @@ -1,7 +1,12 @@ - /** * @file misc.cpp * + * This file contains a miscellaneous collection of global data + * functions. + * + * These modules are defined here: + * globalData + * * $Id$ */ @@ -28,82 +33,120 @@ using namespace std; namespace Cantera { - /** - * Class to hold global data. Class Application is the top-level + /*! + * @defgroup globalData Global Data + * + * Global data are available anywhere. There are two kinds. + * Cantera has an assortment of constant values for physical parameters. + * Also, Cantera maintains a collection of global data which is specific + * to each process that invokes Cantera functions. This process-specific + * data is storred in the class Application. + */ + //@{ + //@} + + //! Class to hold global data. + /*! + * Class Application is the top-level * class that stores data that should persist for the duration of * the process. The class should not be instantiated directly; * instead, it is instantiated as needed by the functions declared * here. At most one instance is created, and it is not destroyed * until the process terminates. + * + * @ingroup HTML_logs + * @ingroup textlogs + * @ingroup globalData */ - class Application { - public: - Application() : linelen(0), stop_on_error(false), - tmp_dir("."), sleep("1") - { - // if TMP or TEMP is set, use it for the temporary - // directory - char* tmpdir = getenv("TMP"); - if (tmpdir == 0) - tmpdir = getenv("TEMP"); - if (tmpdir != 0) - tmp_dir = string(tmpdir); + class Application { + public: + //! Constructor for class sets up the initial conditions + Application() : linelen(0), stop_on_error(false), + tmp_dir("."), sleep("1") + { + // if TMP or TEMP is set, use it for the temporary + // directory + char* tmpdir = getenv("TMP"); + if (tmpdir == 0) + tmpdir = getenv("TEMP"); + if (tmpdir != 0) + tmp_dir = string(tmpdir); - // if SLEEP is set, use it as the sleep time - char* sleepstr = getenv("SLEEP"); - if (sleepstr != 0) { - sleep = string(sleepstr); - } + // if SLEEP is set, use it as the sleep time + char* sleepstr = getenv("SLEEP"); + if (sleepstr != 0) { + sleep = string(sleepstr); + } - // install a default logwriter that writes to standard - // output / standard error - logwriter = new Logger(); - // HTML log files - xmllog = 0; - current = 0; - loglevel = 0; - } + // install a default logwriter that writes to standard + // output / standard error + logwriter = new Logger(); + // HTML log files + xmllog = 0; + current = 0; + loglevel = 0; + } - /// Delete any open XML trees, the logwriter, and - /// the XML log, if any. - virtual ~Application() { - map::iterator pos; - for (pos = xmlfiles.begin(); pos != xmlfiles.end(); ++pos) { - pos->second->unlock(); - delete pos->second; - pos->second = 0; - } - delete logwriter; - if (xmllog) { - write_logfile("orphan"); - //delete xmllog; - } - } + //! Destructor for class deletes global data + /*! + * Delete any open XML trees, the logwriter, and + * the XML log, if any. + */ + virtual ~Application() { + map::iterator pos; + for (pos = xmlfiles.begin(); pos != xmlfiles.end(); ++pos) { + pos->second->unlock(); + delete pos->second; + pos->second = 0; + } + delete logwriter; + if (xmllog) { + write_logfile("orphan"); + //delete xmllog; + } + } + //! Current vector of input directories to search for input files + vector inputDirs; + //! Current list of error messages + vector errorMessage; + //! Current list of warning messages + vector warning; + //! Current error Routine + vector errorRoutine; + //! Last error message + string msglog; + //! Current line length + size_t linelen; + //! Current value of stop_on_error + bool stop_on_error; + //! Current map of options + map options; + //! Current value of tmp_dir + string tmp_dir; + //! Current vector of xml file trees that have been previously parsed + map xmlfiles; + //! Current sleep command. + string sleep; + //! Current pointer to the logwriter + Logger* logwriter; + //! Current pointer to the top of the XML_Node tree for the current HTML log + XML_Node *xmllog; + //! Pointer to the last current position in the XML_Node tree for the current HTML log + XML_Node *current; + //! Current value of loglevel + int loglevel; + //! Vector of loglevels for loggroups that are open + vector loglevels; + //! Current vector of loggroups that are open + vector loggroups; + }; - vector inputDirs; - vector errorMessage; - vector warning; - vector errorRoutine; - string msglog; - size_t linelen; - bool stop_on_error; - map options; - string tmp_dir; - map xmlfiles; - string sleep; - Logger* logwriter; - XML_Node *xmllog, *current; - int loglevel; - vector loglevels; - vector loggroups; - }; - - /// Return a pointer to the one and only instance of class Application + /// Return a pointer to the one and only instance of class Application Application* app(); - void setDefaultDirectories(); + static void setDefaultDirectories(); /// Pointer to the single Application instance static Application* s_app = 0; @@ -119,7 +162,7 @@ namespace Cantera { } } - /** + /* * Delete all global data. It should be called at the end of the * application if leak checking is to be done. */ @@ -143,7 +186,7 @@ namespace Cantera { } - XML_Node* get_XML_File(string file) { + XML_Node* get_XML_File(std::string file) { string path = ""; /* try { @@ -253,7 +296,7 @@ namespace Cantera { return s_app->xmlfiles[ff]; } - void close_XML_File(string file) { + void close_XML_File(std::string file) { if (file == "all") { map::iterator b = app()->xmlfiles.begin(), e = app()->xmlfiles.end(); @@ -271,7 +314,7 @@ namespace Cantera { } } - void setTmpDir(string tmp) { app()->tmp_dir = tmp; } + void setTmpDir(std::string tmp) { app()->tmp_dir = tmp; } string tmpDir() { appinit(); return app()->tmp_dir; } string sleep() { appinit(); return app()->sleep; } @@ -391,13 +434,10 @@ namespace Cantera { s_app->errorRoutine.push_back(r); } - /// @defgroup inputfiles Input File Handling - /// The properties of phases and interfaces are specified in - /// text files. These procedures handle various aspects of reading - /// these files. - - /** - * Set the default directories for input files. Cantera searches + + //! Set the default directories for input files. + /*! + * %Cantera searches * for input files along a path that includes platform-specific * default locations, and possibly user-specified locations. This * function installs the platform-specific directories on the @@ -408,7 +448,7 @@ namespace Cantera { * Windows platforms, if environment variable COMMONPROGRAMFILES * is set (which it should be on Win XP or Win 2000), then * directories under this one will be added to the search - * path. The Cantera Windows installer installs data files to this + * path. The %Cantera Windows installer installs data files to this * location. * * On the Mac, directory '/Applications/Cantera/data' is added to the @@ -418,12 +458,12 @@ namespace Cantera { * directory name, then this directory is added to the search path. * * Finally, the location where the data files were installed when - * Cantera was built is added to the search path. + * %Cantera was built is added to the search path. * * Additional directories may be added by calling function addDirectory. * @ingroup inputfiles */ - void setDefaultDirectories() { + static void setDefaultDirectories() { appinit(); vector& dirs = s_app->inputDirs; @@ -484,10 +524,9 @@ namespace Cantera { } - - /// Add a directory to the input file search path. - /// @ingroup inputfiles - void addDirectory(string dir) { + // Add a directory to the input file search path. + // @ingroup inputfiles + void addDirectory(std::string dir) { appinit(); if (s_app->inputDirs.size() == 0) setDefaultDirectories(); string d = stripnonprint(dir); @@ -500,15 +539,15 @@ namespace Cantera { s_app->inputDirs.push_back(stripnonprint(dir)); } - /*! + /* * This routine will search for a file in the default * locations specified for the application. * See the routine setDefaultDirectories() listed above. * * The default set of directories specified for the application - * will be searched if a '/' or an '\\' is not found in + * will be searched if a '/' or an '\\' is found in the * name. If either is found then a relative path name is - * presumed and the default directories are not searched. + * presumed, and the default directories are not searched. * * The presence of the file is determined by whether the file * can be opened for reading by the current user. @@ -522,7 +561,7 @@ namespace Cantera { * If the file is not found, a message is written to * stdout and a CanteraError exception is thrown. */ - string findInputFile(string name) { + string findInputFile(std::string name) { appinit(); string::size_type islash = name.find('/'); string::size_type ibslash = name.find('\\'); @@ -564,19 +603,18 @@ namespace Cantera { //} } - doublereal toSI(string unit) { + doublereal toSI(std::string unit) { doublereal f = Unit::units()->toSI(unit); if (f) return f; else return 1.0; } - doublereal actEnergyToSI(string unit) { + doublereal actEnergyToSI(std::string unit) { doublereal f = Unit::units()->actEnergyToSI(unit); if (f) return f; else return 1.0; } - string canteraRoot() { char* ctroot = 0; ctroot = getenv("CANTERA_ROOT"); @@ -590,7 +628,6 @@ namespace Cantera { } } - // exceptions CanteraError::CanteraError(std::string proc, std::string msg) { @@ -635,55 +672,53 @@ namespace Cantera { } - /// @defgroup logs Diagnostic Output - /// - /// Writing diagnostic information to the screen or to a file. - /// It is often useful to be able to write diagnostic messages to - /// the screen or to a file. Cantera provides two sets of - /// procedures for this purpose. The first set is designed to - /// write text messages to the screen to document the progress of - /// a complex calculation, such as a flame simulation.The second - /// set writes nested lists in HTML format. This is useful to - /// print debugging output for a complex calculation that calls - /// many different procedures. + // @defgroup logs Diagnostic Output + // + // Writing diagnostic information to the screen or to a file. + // It is often useful to be able to write diagnostic messages to + // the screen or to a file. Cantera provides two sets of + // procedures for this purpose. The first set is designed to + // write text messages to the screen to document the progress of + // a complex calculation, such as a flame simulation.The second + // set writes nested lists in HTML format. This is useful to + // print debugging output for a complex calculation that calls + // many different procedures. - /// @defgroup textlogs Writing messages to the screen - /// @ingroup logs + // @defgroup textlogs Writing messages to the screen + // @ingroup logs - /// Write a message to the screen. The string may be of any - /// length, and may contain end-of-line characters. This method is - /// used throughout Cantera to write log messages. It can also be - /// called by user programs. The advantage of using writelog over - /// writing directly to the standard output is that messages - /// written with writelog will display correctly even when Cantera - /// is used from MATLAB or other application that do not have a - /// standard output stream. @ingroup textlogs - void writelog(const string& msg) { + // Write a message to the screen. The string may be of any + // length, and may contain end-of-line characters. This method is + // used throughout Cantera to write log messages. It can also be + // called by user programs. The advantage of using writelog over + // writing directly to the standard output is that messages + // written with writelog will display correctly even when Cantera + // is used from MATLAB or other application that do not have a + // standard output stream. @ingroup textlogs + void writelog(const std::string& msg) { app()->logwriter->write(msg); } - /// test - /// @ingroup textlogs + // Write a message to the screen. void writelog(const char* msg) {writelog(string(msg));} - /// Write an error message and terminate execution. test. - /// @ingroup textlogs - void error(const string& msg) { + // Write an error message and terminate execution. test. + // @ingroup textlogs + void error(const std::string& msg) { app()->logwriter->error(msg); } - /// test - /// @ingroup textlogs + // @ingroup textlogs int userInterface() { appinit(); return app()->logwriter->env(); } - /// Install a logger. Called by the language interfaces to install an - /// appropriate logger. - /// @see Logger. - /// @ingroup textlogs + // Install a logger. Called by the language interfaces to install an + // appropriate logger. + // @see Logger. + // @ingroup textlogs void setLogger(Logger* logwriter) { appinit(); delete s_app->logwriter; @@ -692,38 +727,38 @@ namespace Cantera { #ifdef WITH_HTML_LOGS + //////////////////////////////////////////////////////////////// + // + // @defgroup HTML_logs Writing HTML Logfiles + // @ingroup logs + // + // These functions are designed to allow writing HTML diagnostic + // messages in a manner that allows users to control how much + // diagnostic output to print. It works like this: Suppose you + // have function A that invokes function B that invokes function + // C. You want to be able to print diagnostic messages just from + // function A, or from A and B, or from A, B, and C, or to turn + // off printing diagnostic messages altogether. All you need to + // do is call 'beginLogGroup' within function A, and specify a + // loglevel value. Then in B, call beginLogGroup again, but + // without an explicit value for loglevel. By default, the + // current level is decremented by one in beginLogGroup. If it + // is <= 0, no log messages are written. Thus, if each function + // begins with beginLogGroup and calls endLogGroup before + // returning, then setting loglevel = 3 will cause messages from + // A, B, and C to be written (in nested HTML lists), loglevel = + // 2 results in messages only being written from A and B, etc. + // ///////////////////////////////////////////////////////////////// - /// - /// @defgroup HTML_logs Writing HTML Logfiles - /// @ingroup logs - /// - /// These functions are designed to allow writing HTML diagnostic - /// messages in a manner that allows users to control how much - /// diagnostic output to print. It works like this: Suppose you - /// have function A that invokes function B that invokes function - /// C. You want to be able to print diagnostic messages just from - /// function A, or from A and B, or from A, B, and C, or to turn - /// off printing diagnostic messages altogether. All you need to - /// do is call 'beginLogGroup' within function A, and specify a - /// loglevel value. Then in B, call beginLogGroup again, but - /// without an explicit value for loglevel. By default, the - /// current level is decremented by one in beginLogGroup. If it - /// is <= 0, no log messages are written. Thus, if each function - /// begins with beginLogGroup and calls endLogGroup before - /// returning, then setting loglevel = 3 will cause messages from - /// A, B, and C to be written (in nested HTML lists), loglevel = - /// 2 results in messages only being written from A and B, etc. - /// - ////////////////////////////////////////////////////////////////// - /// Create a new group for log messages. Usually this is called - /// upon entering the function, with the title parameter equal to - /// the name of the function or method. Subsequent messages - /// written with addLogEntry will appear grouped under this - /// heading, until endLogGroup() is called. - /// @ingroup HTML_logs - void beginLogGroup(string title, int loglevel) { + // Create a new group for log messages. Usually this is called + // upon entering the function, with the title parameter equal to + // the name of the function or method. Subsequent messages + // written with addLogEntry will appear grouped under this + // heading, until endLogGroup() is called. + // @ingroup HTML_logs + void beginLogGroup(std::string title, int loglevel) { appinit(); if (loglevel != -99) s_app->loglevel = loglevel; else s_app->loglevel--; @@ -738,45 +773,45 @@ namespace Cantera { s_app->current = &s_app->current->addChild("ul"); } - /// Add an entry to the log file. Entries appear in the form "tag: - /// value". - /// @ingroup HTML_logs - void addLogEntry(string tag, string value) { + // Add an entry to the log file. Entries appear in the form "tag: + // value". + // @ingroup HTML_logs + void addLogEntry(std::string tag, std::string value) { if (s_app->loglevel > 0 && s_app->current) s_app->current->addChild("li",tag+": "+value); } - /// Add an entry to the log file. Entries appear in the form "tag: - /// value". - /// @ingroup HTML_logs - void addLogEntry(string tag, doublereal value) { + // Add an entry to the log file. Entries appear in the form "tag: + // value". + // @ingroup HTML_logs + void addLogEntry(std::string tag, doublereal value) { if (s_app->loglevel > 0 && s_app->current) s_app->current->addChild("li",tag+": "+fp2str(value)); } - /// Add an entry to the log file. Entries appear in the form "tag: - /// value". - /// @ingroup HTML_logs - void addLogEntry(string tag, int value) { + // Add an entry to the log file. Entries appear in the form "tag: + // value". + // @ingroup HTML_logs + void addLogEntry(std::string tag, int value) { if (s_app->loglevel > 0 && s_app->current) s_app->current->addChild("li",tag+": "+int2str(value)); } - /// Add an entry to the log file. - /// @ingroup HTML_logs - void addLogEntry(string msg) { + // Add an entry to the log file. + // @ingroup HTML_logs + void Cantera::addLogEntry(std::string msg) { if (s_app->loglevel > 0 && s_app->current) s_app->current->addChild("li",msg); } - /// Close the current group of log messages. This is typically - /// called just before leaving a function or method, to close the - /// group of messages that were output from this - /// function. Subsequent messages written with addLogEntry will - /// appear at the next-higher level in the outline, unless - /// beginLogGroup is called first to create a new group. - /// @ingroup HTML_logs - void endLogGroup(string title) { + // Close the current group of log messages. This is typically + // called just before leaving a function or method, to close the + // group of messages that were output from this + // function. Subsequent messages written with addLogEntry will + // appear at the next-higher level in the outline, unless + // beginLogGroup is called first to create a new group. + // @ingroup HTML_logs + void endLogGroup(std::string title) { if (s_app->loglevel > 0) { s_app->current = s_app->current->parent(); s_app->current = s_app->current->parent(); @@ -800,16 +835,16 @@ namespace Cantera { s_app->loggroups.pop_back(); } - /// Write the HTML log file. Log entries are stored in memory in - /// an XML tree until this function is called, which writes the - /// tree to a file and clears the entries stored in memory. The - /// output file will have the name specified in the 'file' - /// argument. If this argument has no extension, the extension - /// '.html' will be appended. Also, if the file already exists, an - /// integer will be appended to the name so that no existing log - /// file will be overwritten. will be appended to the name. - /// @ingroup HTML_logs - void write_logfile(string file) { + // Write the HTML log file. Log entries are stored in memory in + // an XML tree until this function is called, which writes the + // tree to a file and clears the entries stored in memory. The + // output file will have the name specified in the 'file' + // argument. If this argument has no extension, the extension + // '.html' will be appended. Also, if the file already exists, an + // integer will be appended to the name so that no existing log + // file will be overwritten. will be appended to the name. + // @ingroup HTML_logs + void write_logfile(std::string file) { if (!s_app->xmllog) { return; } diff --git a/Cantera/src/thermo/IdealMolalSoln.cpp b/Cantera/src/thermo/IdealMolalSoln.cpp index 30bafe837..59015f68a 100644 --- a/Cantera/src/thermo/IdealMolalSoln.cpp +++ b/Cantera/src/thermo/IdealMolalSoln.cpp @@ -13,11 +13,6 @@ * $Revision$ */ - -#ifndef MAX -#define MAX(x,y) (( (x) > (y) ) ? (x) : (y)) -#endif - #include "IdealMolalSoln.h" #include "importCTML.h" @@ -412,7 +407,7 @@ namespace Cantera { ac[k] = m_molalities[k]; } double xmolSolvent = moleFraction(m_indexSolvent); - xmolSolvent = MAX(8.689E-3, xmolSolvent); + xmolSolvent = fmaxx(8.689E-3, xmolSolvent); ac[m_indexSolvent] = exp((xmolSolvent - 1.0)/xmolSolvent); } @@ -434,7 +429,7 @@ namespace Cantera { acMolality[k] = 1.0; } double xmolSolvent = moleFraction(m_indexSolvent); - xmolSolvent = MAX(8.689E-3, xmolSolvent); + xmolSolvent = fmaxx(8.689E-3, xmolSolvent); acMolality[m_indexSolvent] = exp((xmolSolvent - 1.0)/xmolSolvent) / xmolSolvent; } @@ -485,7 +480,7 @@ namespace Cantera { doublereal RT = GasConstant * temperature(); for (int k = 0; k < m_kk; k++) { if (k != m_indexSolvent) { - xx = MAX(m_molalities[k], xxSmall); + xx = fmaxx(m_molalities[k], xxSmall); mu[k] += RT * log(xx); } } @@ -494,7 +489,7 @@ namespace Cantera { * -> see my notes */ double xmolSolvent = moleFraction(m_indexSolvent); - xx = MAX(xmolSolvent, xxSmall); + xx = fmaxx(xmolSolvent, xxSmall); mu[m_indexSolvent] += (RT * (xmolSolvent - 1.0) / xx); } diff --git a/Cantera/src/thermo/IdealMolalSoln.h b/Cantera/src/thermo/IdealMolalSoln.h index b14ac2345..6ae3060b3 100644 --- a/Cantera/src/thermo/IdealMolalSoln.h +++ b/Cantera/src/thermo/IdealMolalSoln.h @@ -85,16 +85,45 @@ namespace Cantera { /// Constructors IdealMolalSoln(); + + //! Copy Constructor IdealMolalSoln(const IdealMolalSoln &); + + //! Equality operator IdealMolalSoln& operator=(const IdealMolalSoln&); + //! Constructor for phase initialization + /*! + * This constructor will initialize a phase, by reading the required + * information from an input file. + * + * @param inputFile Name of the Input file that contains information about the phase + * @param id id of the phase within the input file + */ IdealMolalSoln(std::string inputFile, std::string id = ""); + + //! Constructor for phase initialization + /*! + * This constructor will initialize a phase, by reading the required + * information from XML_Node tree. + * + * @param phaseRef reference for an XML_Node tree that contains + * the information necessary to initialize the phase. + * @param id id of the phase within the input file + */ IdealMolalSoln(XML_Node& phaseRef, std::string id = ""); /// Destructor. virtual ~IdealMolalSoln(); - + //! Duplication function + /*! + * This virtual function is used to create a duplicate of the + * current phase. It's used to duplicate the phase when given + * a ThermoPhase pointer to the phase. + * + * @return It returns a ThermoPhase pointer. + */ ThermoPhase *duplMyselfAsThermoPhase(); /** @@ -594,6 +623,14 @@ namespace Cantera { * */ virtual void setParameters(int n, doublereal* c); + + /*! + * @internal + * Get the parameters used to initialize the phase. + * + * @param n number of parameters (output) + * @param c array of n coefficients + */ virtual void getParameters(int &n, doublereal * const c); /* @@ -758,14 +795,14 @@ namespace Cantera { */ virtual void initThermoXML(XML_Node& phaseNode, std::string id=""); - /* + /*! * Report the molar volume of species k * * units - \f$ m^3 kmol^-1 \f$ */ double speciesMolarVolume(int k) const; - /* + /*! * Fill in a return vector containing the species molar volumes * units - \f$ m^3 kmol^-1 \f$ */ diff --git a/Cantera/src/thermo/IdealSolidSolnPhase.h b/Cantera/src/thermo/IdealSolidSolnPhase.h index e370c9ef9..f4a3b25b7 100644 --- a/Cantera/src/thermo/IdealSolidSolnPhase.h +++ b/Cantera/src/thermo/IdealSolidSolnPhase.h @@ -34,10 +34,15 @@ namespace Cantera { + /*! + * @name CONSTANTS - Models for the Standard State of IdealSolidSolnPhase's + */ + //@{ const int cIdealSolidSolnPhase0 = 5010; const int cIdealSolidSolnPhase1 = 5011; const int cIdealSolidSolnPhase2 = 5012; - + //@} + /** * Class IdealSolidSolnPhase represents a condensed phase ideal * solution compound. The phase and the pure species phases which @@ -48,7 +53,7 @@ namespace Cantera { * The class derives from class ThermoPhase, * and overloads the virtual methods defined there with ones that * use expressions appropriate for ideal solution mixtures. - *File name for the XML datafile containing information + * File name for the XML datafile containing information * for this phase * The generalized concentrations can have three different forms * depending on the value of the member attribute m_formGC, which @@ -135,17 +140,17 @@ namespace Cantera { */ IdealSolidSolnPhase(XML_Node& root, std::string id="", int formCG=0); - /* + /*! * Copy Constructor */ IdealSolidSolnPhase(const IdealSolidSolnPhase &); - /* + /*! * Assignment operator */ IdealSolidSolnPhase& operator=(const IdealSolidSolnPhase &); - /* + /*! * Base Class Duplication Function * -> given a pointer to ThermoPhase, this function can * duplicate the object. (note has to be a separate function @@ -154,7 +159,7 @@ namespace Cantera { */ virtual ThermoPhase* duplMyselfAsThermoPhase(); - + //! Destructor virtual ~IdealSolidSolnPhase() {} /** diff --git a/Cantera/src/thermo/MolalityVPSSTP.cpp b/Cantera/src/thermo/MolalityVPSSTP.cpp index b2eaa076b..fb37c54c8 100644 --- a/Cantera/src/thermo/MolalityVPSSTP.cpp +++ b/Cantera/src/thermo/MolalityVPSSTP.cpp @@ -12,9 +12,6 @@ * $Date$ * $Revision$ */ -#ifndef MAX -#define MAX(x,y) (( (x) > (y) ) ? (x) : (y)) -#endif #include "MolalityVPSSTP.h" @@ -433,7 +430,7 @@ namespace Cantera { double sum = 0; for (int k = 0; k < m_kk; k++) { if (k != m_indexSolvent) { - sum += MAX(m_molalities[k], 0.0); + sum += fmaxx(m_molalities[k], 0.0); } } double oc = 1.0; diff --git a/Cantera/src/thermo/MolalityVPSSTP.h b/Cantera/src/thermo/MolalityVPSSTP.h index 5b78add66..700b89db0 100644 --- a/Cantera/src/thermo/MolalityVPSSTP.h +++ b/Cantera/src/thermo/MolalityVPSSTP.h @@ -448,9 +448,16 @@ namespace Cantera { protected: + //! Index of the solvent + /*! + * Currently the index of the solvent is hard-coded to the value 0 + */ int m_indexSolvent; + + //! Molecular weight of the Solvent doublereal m_weightSolvent; - /* + + /*! * In any molality implementation, it makes sense to have * a minimum solvent mole fraction requirement, since the * implementation becomes singular in the xmolSolvent=0 @@ -459,14 +466,19 @@ namespace Cantera { * molal_solvent = 0 when xmol_solvent = 0. */ doublereal m_xmolSolventMIN; - /* + /*! * This is the multiplication factor that goes inside * log expressions involving the molalities of species. * Its equal to Wt_0 / 1000. * where Wt_0 = weight of solvent (kg/kmol) */ doublereal m_Mnaught; - + + //! Current value of the molalities of the species in the phase. + /*! + * Note this vector is a mutable quantity. + * units are (kg/kmol) + */ mutable vector_fp m_molalities; private: doublereal err(std::string msg) const; diff --git a/Cantera/src/thermo/VPStandardStateTP.h b/Cantera/src/thermo/VPStandardStateTP.h index d6be98fbb..41ba1b957 100644 --- a/Cantera/src/thermo/VPStandardStateTP.h +++ b/Cantera/src/thermo/VPStandardStateTP.h @@ -401,17 +401,14 @@ namespace Cantera { void initLengths(); protected: - /* - * The last temperature at which the reference thermodynamic - * properties were calculated at. - */ + + //! The last temperature at which the reference thermodynamic properties were calculated at. mutable doublereal m_tlast; - /* - * The last pressure at which the Standard State thermodynamic - * properties were calculated at. - */ + + //! The last pressure at which the Standard State thermodynamic properties were calculated at. mutable doublereal m_plast; - /** + + /*! * Vector containing the species reference enthalpies at T = m_tlast * and P = p_ref. */ diff --git a/Cantera/src/units.h b/Cantera/src/units.h index 593e15845..91b525615 100644 --- a/Cantera/src/units.h +++ b/Cantera/src/units.h @@ -15,11 +15,16 @@ namespace Cantera { class Unit { public: + //! Initialize the static Unit class. static Unit* units() { if (!s_u) s_u = new Unit; return s_u; } + //! Destroy the static Unit class + /*! + * Note this can't be done in a destructor. + */ static void deleteUnit() { if (s_u) { delete s_u; @@ -27,6 +32,7 @@ namespace Cantera { } } + //! Empty Destructor virtual ~Unit() {} /** diff --git a/Cantera/src/utilities.h b/Cantera/src/utilities.h index b0118456c..bca8cbbf1 100755 --- a/Cantera/src/utilities.h +++ b/Cantera/src/utilities.h @@ -17,6 +17,12 @@ namespace Cantera { + /*! + * @defgroup globalUtilFuncs Global Utility Functions + * + */ + //@{ + /** * Maximum of i and j. If \a i and \a j have different types, \a j * is converted to the type of \a i before the comparison. @@ -96,6 +102,26 @@ namespace Cantera { *out = scale_factor * *begin; } + /*! + * Multiply elements of an array, y, by a scale factor, f and add the + * result to an existing array, x. This is essentially a templated daxpy_ + * operation. + * @code + * for (i = 0; i < n; i++) { + * x[i] += f * [i] + * } + * @endcode + * + * It is templated with three parameters. The first template + * is the iterator, InputIter, which controls access to y[]. + * The second template is the iterator OutputIter, which controls + * access to y[]. The third iterator is S, which is f. + * + * @param begin InputIter Iterator for beginning of y[] + * @param end inputIter Iterator for end of y[] + * @param out OutputIter Iterator for beginning of x[] + * @param scale_factor Scale Factor to multiply y[i] by + */ template inline void increment_scale(InputIter begin, InputIter end, OutputIter out, S scale_factor) { @@ -252,6 +278,18 @@ namespace Cantera { return sum; } + //! scale a templated vector by a constant factor. + /*! + * This function is essentially a wrapper around the stl + * function %scale(). The function is has one template + * parameter, OutputIter. OutputIter is a templated iterator + * that points to the vector to be scaled. + * + * @param N Length of the vector + * @param alpha scale factor - double + * @param x Templated Iterator to the start of the vector + * to be scaled. + */ template inline void scale(int N, double alpha, OutputIter x) { //#ifdef DARWINNNN @@ -261,6 +299,8 @@ namespace Cantera { //#endif } + //@} + } diff --git a/tools/doc/Cantera.cfg.in b/tools/doc/Cantera.cfg.in index bc2237b62..5f2ec1392 100755 --- a/tools/doc/Cantera.cfg.in +++ b/tools/doc/Cantera.cfg.in @@ -4,7 +4,7 @@ # Project related configuration options #--------------------------------------------------------------------------- PROJECT_NAME = Cantera -PROJECT_NUMBER = 1.6 +PROJECT_NUMBER = 1.7 OUTPUT_DIRECTORY = @ctroot@/tools/doc CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English @@ -23,7 +23,7 @@ ABBREVIATE_BRIEF = "The $name class" \ an \ the ALWAYS_DETAILED_SEC = YES -INLINE_INHERITED_MEMB = NO +INLINE_INHERITED_MEMB = YES FULL_PATH_NAMES = NO STRIP_FROM_PATH = STRIP_FROM_INC_PATH = @@ -73,7 +73,7 @@ FILE_VERSION_FILTER = #--------------------------------------------------------------------------- QUIET = NO WARNINGS = YES -WARN_IF_UNDOCUMENTED = NO +WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = NO WARN_FORMAT = "$file:$line: $text" @@ -133,6 +133,8 @@ INLINE_SOURCES = NO STRIP_CODE_COMMENTS = NO REFERENCED_BY_RELATION = YES REFERENCES_RELATION = YES +REFERENCES_LINK_SOURCE = YES +USE_HTAGS = NO VERBATIM_HEADERS = YES #--------------------------------------------------------------------------- # configuration options related to the alphabetical class index @@ -233,7 +235,7 @@ PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- -CLASS_DIAGRAMS = NO +CLASS_DIAGRAMS = YES HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES CLASS_GRAPH = YES @@ -244,6 +246,7 @@ TEMPLATE_RELATIONS = YES INCLUDE_GRAPH = YES INCLUDED_BY_GRAPH = YES CALL_GRAPH = NO +CALLER_GRAPH = NO GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png