From 28414eb77d3d7f7181c8c85c7a84f1db6f418a01 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Thu, 18 Apr 2013 22:07:54 +0000 Subject: [PATCH] Cleaned up Doxygen docs for equilibrium functions --- include/cantera/equil/equil.h | 51 +++++++++++++---------------------- src/equil/equilibrate.cpp | 45 ++----------------------------- 2 files changed, 20 insertions(+), 76 deletions(-) diff --git a/include/cantera/equil/equil.h b/include/cantera/equil/equil.h index 2638575c7..caf16d246 100644 --- a/include/cantera/equil/equil.h +++ b/include/cantera/equil/equil.h @@ -1,13 +1,11 @@ +/** + * @file equil.h + * This file contains the definition of some high level general equilibration + * routines. + */ + // Copyright 2001 California Institute of Technology -/** - * @file equil.h - * This file contains the definition of some high level general equilibration - * routines and the text for the module \ref equilfunctions. - * - * It also contains the Module doxygen text for the Equilibration Solver - * capability within %Cantera. see \ref equilfunctions - */ #ifndef CT_KERNEL_EQUIL_H #define CT_KERNEL_EQUIL_H @@ -16,27 +14,19 @@ namespace Cantera { - /*! * @defgroup equilfunctions Equilibrium Solver Capability * * Cantera has several different equilibrium routines. */ -//@{ -//@} - - -//----------------------------------------------------------- -// convenience functions -//----------------------------------------------------------- //! Equilibrate a ThermoPhase object /*! - * Set a single-phase chemical solution to chemical equilibrium. - * This is a convenience function that uses one or the other of - * the two chemical equilibrium solvers. The XY parameter indicates what two - * thermodynamic quantities, other than element composition, are to be held - * constant during the equilibration process. + * Set a single-phase chemical solution to chemical equilibrium. This is a + * convenience function that uses one or the other of the two chemical + * equilibrium solvers. The XY parameter indicates what two thermodynamic + * quantities, other than element composition, are to be held constant during + * the equilibration process. * * @param s ThermoPhase object that will be equilibrated. * @param XY String representation of what two properties @@ -58,11 +48,9 @@ namespace Cantera * a file in HTML format for viewing in a web browser. * @see HTML_logs * - * @return - * Return variable is equal to the number of subroutine attempts - * it took to equilibrate the system. + * @return The number of iterations it took to equilibrate the system. * - * @ingroup equilfunctions + * @ingroup equilfunctions */ int equilibrate(thermo_t& s, const char* XY, int solver = -1, doublereal rtol = 1.0e-9, int maxsteps = VCS_MAXSTEPS, @@ -74,10 +62,9 @@ int equilibrate(thermo_t& s, const char* XY, * thermodynamic quantities, other than element composition, are to be held * constant during the equilibration process. * - * This is the top-level driver for multiphase equilibrium. It - * doesn't do much more than call the equilibrate method of class - * MultiPhase, except that it adds some messages to the logfile, - * if loglevel is set > 0. + * This is the top-level driver for multiphase equilibrium. It doesn't do + * much more than call the equilibrate method of class MultiPhase, except + * that it adds some messages to the logfile, if loglevel is set > 0. * * @param s MultiPhase object that will be equilibrated. * @param XY String representation of what is being held constant @@ -86,11 +73,9 @@ int equilibrate(thermo_t& s, const char* XY, * @param maxiter Maximum iterations * @param loglevel loglevel * - * @return - * Return variable is equal to the number of subroutine attempts - * it took to equilibrate the system. + * @return The number of iterations it took to equilibrate the system. * - * @ingroup equilfunctions + * @ingroup equilfunctions */ doublereal equilibrate(MultiPhase& s, const char* XY, doublereal rtol = 1.0e-9, int maxsteps = 5000, int maxiter = 100, diff --git a/src/equil/equilibrate.cpp b/src/equil/equilibrate.cpp index b893d01af..e645a3511 100644 --- a/src/equil/equilibrate.cpp +++ b/src/equil/equilibrate.cpp @@ -1,8 +1,7 @@ /** - * @file equilibrate.cpp - * Driver routines for the chemical equilibrium solvers. - * + * @file equilibrate.cpp Driver routines for the chemical equilibrium solvers. */ + #include "cantera/equil/equil.h" #include "cantera/equil/ChemEquil.h" #include "cantera/equil/MultiPhaseEquil.h" @@ -12,15 +11,6 @@ namespace Cantera { -/* - * Set a multiphase mixture to a state of chemical equilibrium. - * This is the top-level driver for multiphase equilibrium. It - * doesn't do much more than call the equilibrate method of class - * MultiPhase, except that it adds some messages to the logfile, - * if loglevel is set > 0. - * - * @ingroup equil - */ doublereal equilibrate(MultiPhase& s, const char* XY, doublereal tol, int maxsteps, int maxiter, int loglevel) @@ -66,37 +56,6 @@ doublereal equilibrate(MultiPhase& s, const char* XY, return 0.0; } -/* - * Set a single-phase chemical solution to chemical equilibrium. - * This is a convenience function that uses one or the other of - * the two chemical equilibrium solvers. - * - * @param s The object to set to an equilibrium state - * - * @param XY An integer specifying the two properties to be held - * constant. - * - * @param solver The equilibrium solver to use. If solver = 0, - * the ChemEquil solver will be used, and if solver = 1, the - * MultiPhaseEquil solver will be used (slower than ChemEquil, - * but more stable). If solver < 0 (default, then ChemEquil will - * be tried first, and if it fails MultiPhaseEquil will be tried. - * - * @param maxsteps The maximum number of steps to take to find - * the solution. - * - * @param maxiter For the MultiPhaseEquil solver only, this is - * the maximum number of outer temperature or pressure iterations - * to take when T and/or P is not held fixed. - * - * @param loglevel Controls amount of diagnostic output. loglevel - * = 0 suppresses diagnostics, and increasingly-verbose messages - * are written as loglevel increases. The messages are written to - * a file in HTML format for viewing in a web browser. - * @see HTML_logs - * - * @ingroup equil - */ int equilibrate(thermo_t& s, const char* XY, int solver, doublereal rtol, int maxsteps, int maxiter, int loglevel) {