diff --git a/Cantera/src/base/Array.h b/Cantera/src/base/Array.h index 191c50ac3..003700a8c 100755 --- a/Cantera/src/base/Array.h +++ b/Cantera/src/base/Array.h @@ -38,14 +38,27 @@ namespace Cantera { public: + //! Type definition for the iterator class that is + //! can be used by Array2D types. + /*! + * this is just equal to vector_fp iterator. + */ typedef vector_fp::iterator iterator; + + + //! Type definition for the const_iterator class that is + //! can be used by Array2D types. + /*! + * this is just equal to vector_fp const_iterator. + */ typedef vector_fp::const_iterator const_iterator; /** * Default constructor. Create an empty array. */ - Array2D() : m_nrows(0), m_ncols(0) { m_data.clear(); } - + Array2D() : m_nrows(0), m_ncols(0) { + m_data.clear(); + } //! Constructor. /*! @@ -86,7 +99,7 @@ namespace Cantera { return *this; } - //! resize the array, and fill the new entries with 'v' + //! Resize the array, and fill the new entries with 'v' /*! * @param n This is the number of rows * @param m This is the number of columns in the new matrix @@ -98,7 +111,14 @@ namespace Cantera { m_data.resize(n*m, v); } - /// append a column + //! Append a column to the existing matrix using a std vector + /*! + * This operation will add a column onto the existing matrix. + * + * @param c This vector is the entries in the + * column to be added. It must have a length + * equal to m_nrows or greater. + */ void appendColumn(const vector_fp& c) { m_ncols++; m_data.resize(m_nrows*m_ncols); @@ -106,37 +126,66 @@ namespace Cantera { for (m = 0; m < m_nrows; m++) value(m_ncols, m) = c[m]; } - /// append a column - void appendColumn(doublereal* c) { + //! Append a column to the existing matrix + /*! + * This operation will add a column onto the existing matrix. + * + * @param c This vector of doubles is the entries in the + * column to be added. It must have a length + * equal to m_nrows or greater. + */ + void appendColumn(const doublereal* const c) { m_ncols++; m_data.resize(m_nrows*m_ncols); int m; for (m = 0; m < m_nrows; m++) value(m_ncols, m) = c[m]; } - /// set the nth row to array rw - void setRow(int n, doublereal* rw) { + //! Set the nth row to array rw + /*! + * @param n Index of the row to be changed + * @param rw Vector for the row. Must have a length of m_ncols. + */ + void setRow(int n, const doublereal* const rw) { for (int j = 0; j < m_ncols; j++) { m_data[m_nrows*j + n] = rw[j]; } } - /// get the nth row - void getRow(int n, doublereal* rw) { + //! Get the nth row and return it in a vector + /*! + * @param n Index of the row to be returned. + * @param rw Return Vector for the operation. + * Must have a length of m_ncols. + */ + void getRow(int n, doublereal* const rw) { for (int j = 0; j < m_ncols; j++) { rw[j] = m_data[m_nrows*j + n]; } } - /// set the values in column m to those in array col - void setColumn(int m, doublereal* col) { + //! Set the values in column m to those in array col + /*! + * A(i,m) = col(i) + * + * @param m Column to set + * @param col pointer to a col vector. Vector + * must have a length of m_nrows. + */ + void setColumn(int m, doublereal* const col) { for (int i = 0; i < m_nrows; i++) { m_data[m_nrows*m + i] = col[i]; } } - /// get the values in column m - void getColumn(int m, doublereal* col) { + //! Get the values in column m + /*! + * col(i) = A(i,m) + * + * @param m Column to set + * @param col pointer to a col vector that will be returned + */ + void getColumn(int m, doublereal* const col) { for (int i = 0; i < m_nrows; i++) { col[i] = m_data[m_nrows*m + i]; } @@ -147,10 +196,18 @@ namespace Cantera { * heap. */ virtual ~Array2D(){} - - - /** - * Evaluate a*x + y. + + //! Evaluate z = a*x + y. + /*! + * This function evaluates the AXPY operation, and stores + * the result in the object's Array2D object. + * It's assumed that all 3 objects have the same dimensions, + * but no error checking is done. + * + * @param a scalar to multiply x with + * @param x First Array2D object to be used + * @param y Second Array2D object to be used + * */ void axpy(doublereal a, const Array2D& x, const Array2D& y) { iterator b = begin(); @@ -169,20 +226,43 @@ namespace Cantera { */ doublereal& operator()( int i, int j) { return value(i,j); } - /** - * Allows retrieving elements using the syntax x = A(i,j). + + //! Allows retrieving elements using the syntax x = A(i,j). + /*! + * @param i Index for the row to be retrieved + * @param j Index for the column to be retrieved. + * + * @return Returns the value of the matrix entry */ - doublereal operator() ( int i, int j) const {return value(i,j);} + doublereal operator() (int i, int j) const { + return value(i,j); + } //! Returns a changeable reference to position in the matrix /*! * This is a key entry. Returns a reference to the matrixes (i,j) * element. This may be used as an L value. + * + * @param i The row index + * @param j The column index + * + * @return Returns a changeable reference to the matrix entry + */ + doublereal& value(int i, int j) { + return m_data[m_nrows*j + i]; + } + + //! Returns the value of a single matrix entry + /*! + * This is a key entry. Returns the value of the matrix position (i,j) + * element. + * * @param i The row index * @param j The column index */ - doublereal& value( int i, int j) {return m_data[m_nrows*j + i];} - doublereal value( int i, int j) const {return m_data[m_nrows*j + i];} + doublereal value(int i, int j) const { + return m_data[m_nrows*j + i]; + } /// Number of rows size_t nRows() const { return m_nrows; } @@ -208,10 +288,25 @@ namespace Cantera { /// Return a const reference to the data vector const vector_fp& data() const { return m_data; } - /// Return a pointer to the top of column j, columns are contiguous - /// in memory + //! Return a pointer to the top of column j, columns are contiguous + //! in memory + /*! + * @param j Value of the column + * + * @return Returns a pointer to the top of the column + */ doublereal * ptrColumn(int j) { return &(m_data[m_nrows*j]); } - const doublereal * ptrColumn(int j) const { return &(m_data[m_nrows*j]); } + + //! Return a const pointer to the top of column j, columns are contiguous + //! in memory + /*! + * @param j Value of the column + * + * @return Returns a const pointer to the top of the column + */ + const doublereal * ptrColumn(int j) const { + return &(m_data[m_nrows*j]); + } protected: @@ -225,7 +320,16 @@ namespace Cantera { int m_ncols; }; - /// output the array + //! Output the current contents of the Array2D object + /*! + * Example of usage: + * s << m << endl; + * + * @param s Reference to the ostream to write to + * @param m Object of type Array2D that you are querying + * + * @return Returns a reference to the ostream. + */ inline std::ostream& operator<<(std::ostream& s, const Array2D& m) { int nr = static_cast(m.nRows()); int nc = static_cast(m.nColumns()); diff --git a/Cantera/src/base/misc.cpp b/Cantera/src/base/misc.cpp index 692d90bb0..f0a9d8e8e 100755 --- a/Cantera/src/base/misc.cpp +++ b/Cantera/src/base/misc.cpp @@ -1519,10 +1519,6 @@ protected: app()->writelog(msg); } - void writelogAM(const std::string& msg) { - app()->writelog(msg); - } - // Write a message to the screen void Application::Messages::writelog(const std::string& msg) { logwriter->write(msg); @@ -1532,9 +1528,6 @@ protected: void writelog(const char* msg) { app()->writelog(msg); } - void writelogAM(const char* msg) { - app()->writelog(msg); - } // Write a message to the screen void Application::Messages::writelog(const char* pszmsg) { diff --git a/Cantera/src/base/vec_functions.h b/Cantera/src/base/vec_functions.h index 3fce9dae9..3b74ca33c 100755 --- a/Cantera/src/base/vec_functions.h +++ b/Cantera/src/base/vec_functions.h @@ -39,9 +39,13 @@ namespace Cantera { std::copy(x.begin(), x.begin() + n, y.begin()); } - /** - * Divide each element of x by the corresponding element of y. + //! Divide each element of x by the corresponding element of y. + /*! * This function replaces x[n] by x[n]/y[n], for 0 <= n < x.size() + * + * @param x Numerator object of the division operation with template type T + * At the end of the calculation, it contains the result. + * @param y Denominator object of the division template type T */ template inline void divide_each(T& x, const T& y) { @@ -49,9 +53,15 @@ namespace Cantera { x.begin(), std::divides()); } - /** - * multiply each element of x by the corresponding element of y. + //! Multiply each element of x by the corresponding element of y. + /*! * This function replaces x[n] by x[n]*y[n], for 0 <= n < x.size() + * This is a templated function with just one template type. + * + * @param x First object of the multiplication with template type T + * At the end of the calculation, it contains the result. + * @param y Second object of the multiplication with template type T + * */ template inline void multiply_each(T& x, const T& y) { @@ -59,32 +69,52 @@ namespace Cantera { x.begin(), std::multiplies()); } - /** - * Multiply each element of x by scale_factor. + //! Multiply each element of x by scale_factor. + /*! + * This function replaces x[n] by x[n]*scale_factor, for 0 <= n < x.size() + * + * @param x First object of the multiplication with template type T + * At the end of the calculation, it contains the result. + * @param scale_factor scale factor with template type S */ template inline void scale(T& x, S scale_factor) { scale(x.begin(), x.end(), x.begin(), scale_factor); } - /** + //! Return the templated dot product of two objects + /*! * Returns the sum of x[n]*y[n], for 0 <= n < x.size(). + * + * @param x First object of the dot product with template type T + * At the end of the calculation, it contains the result. + * @param y Second object of the dot product with template type T */ template inline doublereal dot_product(const T& x, const T& y) { return std::inner_product(x.begin(), x.end(), y.begin(), 0.0); } + //! Returns the templated dot ratio of two objects /** * Returns the sum of x[n]/y[n], for 0 <= n < x.size(). + * + * @param x First object of the dot product with template type T + * At the end of the calculation, it contains the result. + * @param y Second object of the dot product with template type T */ template inline doublereal dot_ratio(const T& x, const T& y) { return _dot_ratio(x.begin(), x.end(), y.begin(), 0.0); } + //! Returns a templated addition operation of two objects /** * Replaces x[n] by x[n] + y[n] for 0 <= n < x.size() + * + * @param x First object of the addition with template type T + * At the end of the calculation, it contains the result. + * @param y Second object of the addition with template type T */ template inline void add_each(T& x, const T& y) { @@ -119,9 +149,13 @@ namespace Cantera { return start_value; } - /** - * Finds the entry in a vector with maximum absolute - * value, and return this value. + + //! Finds the entry in a vector with maximum absolute + //! value, and return this value. + /*! + * @param v Vector to be queried for maximum value, with template type T + * + * @return Returns an object of type T that is the maximum value, */ template inline T absmax(const std::vector& v) { diff --git a/Cantera/src/equil/MultiPhase.h b/Cantera/src/equil/MultiPhase.h index 8bd66fbb9..7dfa0a5a3 100644 --- a/Cantera/src/equil/MultiPhase.h +++ b/Cantera/src/equil/MultiPhase.h @@ -496,7 +496,8 @@ namespace Cantera { //! Adds moles of a certain species to the mixture /*! - * + * @param indexS Index of the species in the MultiPhase object + * @param addedMoles Value of the moles that are added to the species. */ void addSpeciesMoles(const int indexS, const doublereal addedMoles); diff --git a/Cantera/src/equil/vcs_internal.h b/Cantera/src/equil/vcs_internal.h index d4fd32eeb..6756c4a7a 100644 --- a/Cantera/src/equil/vcs_internal.h +++ b/Cantera/src/equil/vcs_internal.h @@ -474,6 +474,15 @@ namespace VCSnonideal { */ void vcs_print_line(const char *str, int num); + //! Returns a const char string representing the type of the + //! species given by the first argument + /*! + * @param speciesStatus Species status integer representing the type + * of the species. + * @param length Maximum length of the string to be returned. + * Shorter values will yield abbreviated strings. + * Defaults to a value of 100. + */ const char *vcs_speciesType_string(int speciesStatus, int length = 100); //! Print a string within a given space limit diff --git a/Cantera/src/thermo/Crystal.h b/Cantera/src/thermo/Crystal.h index 009ee4857..efe4a8c3b 100644 --- a/Cantera/src/thermo/Crystal.h +++ b/Cantera/src/thermo/Crystal.h @@ -53,6 +53,16 @@ namespace Cantera { }; + //! Prints out the current internal state of the Crystal ThermoPhase object + /*! + * Example of usage: + * s << x << endl; + * + * @param s Reference to the ostream to write to + * @param x Object of type Crystal that you are querying + * + * @return Returns a reference to the ostream. + */ inline std::ostream& operator<<(std::ostream& s, Cantera::Crystal& x) { size_t ip; for (ip = 0; ip < x.nPhases(); ip++) { diff --git a/Cantera/src/thermo/HMWSoln.h b/Cantera/src/thermo/HMWSoln.h index e476d3069..7c55e8ab4 100644 --- a/Cantera/src/thermo/HMWSoln.h +++ b/Cantera/src/thermo/HMWSoln.h @@ -551,7 +551,6 @@ namespace Cantera { * It can be shown that the expression * * - * * \f[ * B^{\phi}_{ca} = \beta^{(0)}_{ca} + \beta^{(1)}_{ca} \exp{(- \alpha^{(1)}_{ca} \sqrt{I})} * + \beta^{(2)}_{ca} \exp{(- \alpha^{(2)}_{ca} \sqrt{I} )} @@ -3201,6 +3200,7 @@ namespace Cantera { //! gamma_o value for the cutoff process at the zero solvent point doublereal MC_X_o_min_; + //! Parameter in the Molality Exp cutoff treatment /*! * This is the slope of the p function at the zero solvent point @@ -3223,10 +3223,16 @@ namespace Cantera { //! Parameter in the Molality Exp cutoff treatment doublereal MC_cpCut_; + //! Parameter in the Molality Exp cutoff treatment doublereal CROP_ln_gamma_o_min; + + //! Parameter in the Molality Exp cutoff treatment doublereal CROP_ln_gamma_o_max; + //! Parameter in the Molality Exp cutoff treatment doublereal CROP_ln_gamma_k_min; + + //! Parameter in the Molality Exp cutoff treatment doublereal CROP_ln_gamma_k_max; //! This is a boolean-type vector indicating whether @@ -3500,7 +3506,10 @@ namespace Cantera { //! Precalculate the IMS Cutoff parameters for typeCutoff = 2 void calcIMSCutoffParams_(); + + //! Calculate molality cut-off parameters void calcMCCutoffParams_(); + //! Utility function to assign an integer value from a string //! for the ElectrolyteSpeciesType field. /*! diff --git a/Cantera/src/thermo/State.h b/Cantera/src/thermo/State.h index 9265013fe..b5bd5eca8 100755 --- a/Cantera/src/thermo/State.h +++ b/Cantera/src/thermo/State.h @@ -335,7 +335,12 @@ namespace Cantera { //! True if the number species has been set bool ready() const; - + //! Every time the mole fractions have changed, this routine + //! will increment the stateMFNumber + /*! + * @param forceChange If this is true then the stateMFNumber always + * changes. This defaults to false. + */ void stateMFChangeCalc(bool forceChange = false); //! Return the state number @@ -423,7 +428,7 @@ namespace Cantera { }; - + //! Return the State Mole Fraction Number inline int State::stateMFNumber() const { return m_stateNum; } diff --git a/Cantera/src/thermo/WaterSSTP.cpp b/Cantera/src/thermo/WaterSSTP.cpp index 4bd2c8db8..af1922645 100644 --- a/Cantera/src/thermo/WaterSSTP.cpp +++ b/Cantera/src/thermo/WaterSSTP.cpp @@ -127,11 +127,6 @@ namespace Cantera { - void WaterSSTP::constructPhase() { - throw CanteraError("WaterSSTP::constructPhase()", "unimplemented"); - - } - /* * @param infile XML file containing the description of the diff --git a/Cantera/src/thermo/WaterSSTP.h b/Cantera/src/thermo/WaterSSTP.h index b8bfdac46..bbc46b18a 100644 --- a/Cantera/src/thermo/WaterSSTP.h +++ b/Cantera/src/thermo/WaterSSTP.h @@ -400,13 +400,24 @@ namespace Cantera { */ virtual doublereal vaporFraction() const; - + //! Set the temperature of the phase + /*! + * The density and composition of the phase is constant during this + * operator. + * + * @param temp Temperature (Kelvin) + */ virtual void setTemperature(const doublereal temp); + //! Set the density of the phase + /*! + * The temperature and composition of the phase is constant during this + * operator. + * + * @param dens value of the density in kg m-3 + */ virtual void setDensity(const doublereal dens); - void constructPhase(); - //! Initialization of a pure water phase using an //! xml file.