From 65c4680e6d0fbbeac0ef7b9b487baa9fc9c4e676 Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Fri, 7 Jul 2023 07:37:19 -0600 Subject: [PATCH 1/8] [docs] Fix doxygen warning in vcs_VolPhase --- include/cantera/equil/vcs_VolPhase.h | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/include/cantera/equil/vcs_VolPhase.h b/include/cantera/equil/vcs_VolPhase.h index 0a46800cd3..107b878c99 100644 --- a/include/cantera/equil/vcs_VolPhase.h +++ b/include/cantera/equil/vcs_VolPhase.h @@ -324,6 +324,7 @@ class vcs_VolPhase //! Sets the creationMoleNum's within the phase object /*! * @param n_k Pointer to a vector of n_k's + * @param creationGlobalRxnNumbers Vector of global creation reaction numbers */ void setCreationMoleNumbers(const double* const n_k, const std::vector &creationGlobalRxnNumbers); @@ -396,9 +397,6 @@ class vcs_VolPhase * @param spIndex local species index (0 to the number of species * in the phase) * @param spGlobalIndex Global species index (across all phases) - * - * @returns the VCS_SOLVE species index of the that species This changes as - * rearrangements are carried out. */ void setSpGlobalIndexVCS(const size_t spIndex, const size_t spGlobalIndex); From 1c2124687fdb3d7cc21d48eca03a491653c16478 Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Fri, 7 Jul 2023 07:37:51 -0600 Subject: [PATCH 2/8] [docs] Consolidate chemical equilibrium documentation --- include/cantera/equil/ChemEquil.h | 5 +++-- include/cantera/equil/MultiPhase.h | 13 +++++-------- include/cantera/equil/MultiPhaseEquil.h | 2 +- include/cantera/equil/vcs_MultiPhaseEquil.h | 2 +- include/cantera/equil/vcs_solve.h | 4 ++-- include/cantera/thermo/ThermoPhase.h | 4 ++-- src/equil/MultiPhase.cpp | 2 +- 7 files changed, 15 insertions(+), 17 deletions(-) diff --git a/include/cantera/equil/ChemEquil.h b/include/cantera/equil/ChemEquil.h index d51e9785e9..4ec1889f8f 100644 --- a/include/cantera/equil/ChemEquil.h +++ b/include/cantera/equil/ChemEquil.h @@ -52,7 +52,8 @@ class EquilOpt }; /** - * @defgroup equil Chemical Equilibrium + * @defgroup equilGroup Chemical Equilibrium + * @details Classes and functions used for calculating chemical equilibrium. */ /** @@ -72,7 +73,7 @@ class EquilOpt * non-zero mole fractions, precisely stoichiometric compositions (for example, * 2 H2 + O2). In general, if speed is important, this solver should be tried first, * and if it fails then use MultiPhaseEquil. - * @ingroup equil + * @ingroup equilGroup */ class ChemEquil { diff --git a/include/cantera/equil/MultiPhase.h b/include/cantera/equil/MultiPhase.h index 5b1410ac37..5f33f743e2 100644 --- a/include/cantera/equil/MultiPhase.h +++ b/include/cantera/equil/MultiPhase.h @@ -1,7 +1,7 @@ /** * @file MultiPhase.h * Headers for the \link Cantera::MultiPhase MultiPhase\endlink - * object that is used to set up multiphase equilibrium problems (see \ref equilfunctions). + * object that is used to set up multiphase equilibrium problems (see \ref equilGroup). */ // This file is part of Cantera. See License.txt in the top-level directory or @@ -17,9 +17,6 @@ namespace Cantera class ThermoPhase; -//! @defgroup equilfunctions Classes and functions used for calculating -//! chemical equilibrium. - //! A class for multiphase mixtures. The mixture can contain any //! number of phases of any type. /*! @@ -54,7 +51,7 @@ class ThermoPhase; * of the species in all the phases that comprise the MultiPhase. The ordering * of species is contiguous with respect to the phase id. * - * @ingroup equilfunctions + * @ingroup equilGroup */ class MultiPhase { @@ -359,7 +356,7 @@ class MultiPhase * log_level=0 suppresses diagnostics, and increasingly-verbose * messages are written as loglevel increases. * - * @ingroup equilfunctions + * @ingroup equilGroup */ void equilibrate(const std::string& XY, const std::string& solver="auto", double rtol=1e-9, int max_steps=50000, int max_iter=100, @@ -698,7 +695,7 @@ std::ostream& operator<<(std::ostream& s, MultiPhase& x); * @param[out] formRxnMatrix * @return The number of components. * - * @ingroup equilfunctions + * @ingroup equilGroup */ size_t BasisOptimize(int* usedZeroedSpecies, bool doFormRxn, MultiPhase* mphase, std::vector& orderVectorSpecies, @@ -741,7 +738,7 @@ size_t BasisOptimize(int* usedZeroedSpecies, bool doFormRxn, * @param[out] orderVectorElements Output vector containing the order of the * elements that is necessary for calculation of the formula matrix. * - * @ingroup equilfunctions + * @ingroup equilGroup */ void ElemRearrange(size_t nComponents, const vector_fp& elementAbundances, MultiPhase* mphase, diff --git a/include/cantera/equil/MultiPhaseEquil.h b/include/cantera/equil/MultiPhaseEquil.h index 7ef7087877..1474f0076e 100644 --- a/include/cantera/equil/MultiPhaseEquil.h +++ b/include/cantera/equil/MultiPhaseEquil.h @@ -27,7 +27,7 @@ namespace Cantera * method of class MultiPhase, although there is no reason it cannot be used * directly in application programs if desired. * - * @ingroup equil + * @ingroup equilGroup */ class MultiPhaseEquil { diff --git a/include/cantera/equil/vcs_MultiPhaseEquil.h b/include/cantera/equil/vcs_MultiPhaseEquil.h index 7acf963d03..08ce92f588 100644 --- a/include/cantera/equil/vcs_MultiPhaseEquil.h +++ b/include/cantera/equil/vcs_MultiPhaseEquil.h @@ -25,7 +25,7 @@ namespace Cantera * argument, and the return parameters are contained in underlying ThermoPhase * objects. * - * @ingroup equilfunctions + * @ingroup equilGroup */ class vcs_MultiPhaseEquil { diff --git a/include/cantera/equil/vcs_solve.h b/include/cantera/equil/vcs_solve.h index 016361cbbd..8bcb1d13b2 100644 --- a/include/cantera/equil/vcs_solve.h +++ b/include/cantera/equil/vcs_solve.h @@ -1,7 +1,7 @@ /** * @file vcs_solve.h Header file for the internal object that holds the vcs * equilibrium problem (see Class \link Cantera::VCS_SOLVE - * VCS_SOLVE\endlink and \ref equilfunctions ). + * VCS_SOLVE\endlink and \ref equilGroup ). */ // This file is part of Cantera. See License.txt in the top-level directory or @@ -527,7 +527,7 @@ class VCS_SOLVE * in the private data structure. All references to the species * properties must employ the ind[] index vector. * 4. Initialization of arrays to zero. - * 5. Check to see if the problem is well posed (If all the element + * 5. Check to see if the problem is well posed (If all the element * abundances are zero, the algorithm will fail) * * @param printLvl Print level of the routine diff --git a/include/cantera/thermo/ThermoPhase.h b/include/cantera/thermo/ThermoPhase.h index 3697560a40..084a5df5e4 100644 --- a/include/cantera/thermo/ThermoPhase.h +++ b/include/cantera/thermo/ThermoPhase.h @@ -294,7 +294,7 @@ class ThermoPhase : public Phase //! Return the speed of sound. Units: m/s. /*! - * The speed of sound is defined as + * The speed of sound is defined as * \f[ * c = \sqrt{\left(\frac{\partial P}{\partial\rho}\right)_s} * \f] @@ -1493,7 +1493,7 @@ class ThermoPhase : public Phase * log_level=0 suppresses diagnostics, and increasingly-verbose * messages are written as loglevel increases. * - * @ingroup equilfunctions + * @ingroup equilGroup */ void equilibrate(const std::string& XY, const std::string& solver="auto", double rtol=1e-9, int max_steps=50000, int max_iter=100, diff --git a/src/equil/MultiPhase.cpp b/src/equil/MultiPhase.cpp index ad2749dfbf..69ae292bcf 100644 --- a/src/equil/MultiPhase.cpp +++ b/src/equil/MultiPhase.cpp @@ -1,7 +1,7 @@ /** * @file MultiPhase.cpp * Definitions for the \link Cantera::MultiPhase MultiPhase\endlink - * object that is used to set up multiphase equilibrium problems (see \ref equilfunctions). + * object that is used to set up multiphase equilibrium problems (see \ref equilGroup). */ // This file is part of Cantera. See License.txt in the top-level directory or From 443445af0539b0a9f02956b17df03c3020527b1b Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Fri, 7 Jul 2023 08:39:12 -0600 Subject: [PATCH 3/8] [docs] Restructure Kinetics doxygen documentation --- include/cantera/kinetics/Arrhenius.h | 10 +----- include/cantera/kinetics/BulkKinetics.h | 3 +- include/cantera/kinetics/ChebyshevRate.h | 2 ++ include/cantera/kinetics/Custom.h | 1 + include/cantera/kinetics/EdgeKinetics.h | 2 +- include/cantera/kinetics/Falloff.h | 11 +------ include/cantera/kinetics/GasKinetics.h | 3 +- include/cantera/kinetics/ImplicitSurfChem.h | 2 +- include/cantera/kinetics/InterfaceKinetics.h | 3 +- include/cantera/kinetics/InterfaceRate.h | 24 ++++++++------ include/cantera/kinetics/Kinetics.h | 11 +++++-- include/cantera/kinetics/KineticsFactory.h | 14 +++++--- include/cantera/kinetics/MultiRate.h | 1 + include/cantera/kinetics/MultiRateBase.h | 1 + include/cantera/kinetics/PlogRate.h | 1 + include/cantera/kinetics/Reaction.h | 3 +- include/cantera/kinetics/ReactionData.h | 1 + include/cantera/kinetics/ReactionRate.h | 1 + .../cantera/kinetics/ReactionRateDelegator.h | 1 + .../cantera/kinetics/ReactionRateFactory.h | 32 +++++++++++++++++-- include/cantera/kinetics/StoichManager.h | 2 ++ include/cantera/kinetics/ThirdBodyCalc.h | 1 + 22 files changed, 82 insertions(+), 48 deletions(-) diff --git a/include/cantera/kinetics/Arrhenius.h b/include/cantera/kinetics/Arrhenius.h index d598045a39..f7812a693d 100644 --- a/include/cantera/kinetics/Arrhenius.h +++ b/include/cantera/kinetics/Arrhenius.h @@ -33,20 +33,12 @@ struct ArrheniusData : public ReactionData }; -/** - * @defgroup arrheniusGroup Arrhenius-type Parameterizations - * - * This section describes the parameterizations used to describe the standard - * Arrhenius rate parameterization and derived models. - * - * @ingroup chemkinetics - */ - //! Base class for Arrhenius-type Parameterizations /*! * This base class provides a minimally functional interface that allows for parameter * access from derived classes as well as classes that use Arrhenius-type expressions * internally, for example FalloffRate and PlogRate. + * @ingroup arrheniusGroup */ class ArrheniusBase : public ReactionRate { diff --git a/include/cantera/kinetics/BulkKinetics.h b/include/cantera/kinetics/BulkKinetics.h index cb0e7656ae..39138a45e1 100644 --- a/include/cantera/kinetics/BulkKinetics.h +++ b/include/cantera/kinetics/BulkKinetics.h @@ -1,6 +1,5 @@ /** * @file BulkKinetics.h - * @ingroup chemkinetics */ // This file is part of Cantera. See License.txt in the top-level directory or @@ -17,7 +16,7 @@ namespace Cantera { //! Specialization of Kinetics for chemistry in a single bulk phase -//! @ingroup kinetics +//! @ingroup kineticsmgr class BulkKinetics : public Kinetics { public: diff --git a/include/cantera/kinetics/ChebyshevRate.h b/include/cantera/kinetics/ChebyshevRate.h index 1a923290a1..ec9e4485e8 100644 --- a/include/cantera/kinetics/ChebyshevRate.h +++ b/include/cantera/kinetics/ChebyshevRate.h @@ -85,6 +85,8 @@ struct ChebyshevData : public ReactionData * Chebyshev polynomials are not defined outside the interval (-1,1), and * therefore extrapolation of rates outside the range of temperatures and * pressures for which they are defined is strongly discouraged. + * + * @ingroup otherRateGroup */ class ChebyshevRate final : public ReactionRate { diff --git a/include/cantera/kinetics/Custom.h b/include/cantera/kinetics/Custom.h index 02353b16f3..1f1a39d7c0 100644 --- a/include/cantera/kinetics/Custom.h +++ b/include/cantera/kinetics/Custom.h @@ -32,6 +32,7 @@ class Func1; * * @warning This class is an experimental part of the %Cantera API and * may be changed or removed without notice. + * @ingroup otherRateGroup */ class CustomFunc1Rate final : public ReactionRate { diff --git a/include/cantera/kinetics/EdgeKinetics.h b/include/cantera/kinetics/EdgeKinetics.h index 048f9a88ee..b2dd471c47 100644 --- a/include/cantera/kinetics/EdgeKinetics.h +++ b/include/cantera/kinetics/EdgeKinetics.h @@ -1,7 +1,6 @@ /** * @file EdgeKinetics.h * - * @ingroup chemkinetics * @ingroup electrochem */ @@ -18,6 +17,7 @@ namespace Cantera /** * Heterogeneous reactions at one-dimensional interfaces between * multiple adjacent two-dimensional surfaces. + * @ingroup kineticsmgr */ class EdgeKinetics : public InterfaceKinetics { diff --git a/include/cantera/kinetics/Falloff.h b/include/cantera/kinetics/Falloff.h index 11e2abe5e3..3827965650 100644 --- a/include/cantera/kinetics/Falloff.h +++ b/include/cantera/kinetics/Falloff.h @@ -12,16 +12,6 @@ namespace Cantera class AnyMap; -/** - * @defgroup falloffGroup Falloff Parameterizations - * - * This section describes the parameterizations used to describe - * the fall-off in reaction rate constants due to intermolecular - * energy transfer. - * @ingroup chemkinetics - */ - - //! Data container holding shared data specific to Falloff rates /** * The data container `FalloffData` holds precalculated data common to @@ -76,6 +66,7 @@ struct FalloffData : public ReactionData * Base class for falloff rate calculators. Each instance of a subclass of FalloffRate * calculates the falloff reaction rate based on specific implementations of the * falloff function. + * @ingroup falloffGroup */ class FalloffRate : public ReactionRate { diff --git a/include/cantera/kinetics/GasKinetics.h b/include/cantera/kinetics/GasKinetics.h index 463955aae9..0dd23a305d 100644 --- a/include/cantera/kinetics/GasKinetics.h +++ b/include/cantera/kinetics/GasKinetics.h @@ -1,6 +1,5 @@ /** * @file GasKinetics.h - * @ingroup chemkinetics */ // This file is part of Cantera. See License.txt in the top-level directory or @@ -24,7 +23,7 @@ namespace Cantera * Kinetics manager for elementary gas-phase chemistry. This kinetics manager * implements standard mass-action reaction rate expressions for low-density * gases. - * @ingroup kinetics + * @ingroup kineticsmgr * @deprecated Replace with BulkKinetics. To be removed after Cantera 3.0. */ class GasKinetics : public BulkKinetics diff --git a/include/cantera/kinetics/ImplicitSurfChem.h b/include/cantera/kinetics/ImplicitSurfChem.h index 19cedfca00..8cde1cf920 100644 --- a/include/cantera/kinetics/ImplicitSurfChem.h +++ b/include/cantera/kinetics/ImplicitSurfChem.h @@ -51,7 +51,7 @@ namespace Cantera * phase with \f$ N_s \f$ surface sites, it consists of the surface coverages * \f$ \theta_k \f$ for \f$ k = 0, N_s - 1 \f$ * - * @ingroup kineticsmgr + * @ingroup chemkinetics */ class ImplicitSurfChem : public FuncEval { diff --git a/include/cantera/kinetics/InterfaceKinetics.h b/include/cantera/kinetics/InterfaceKinetics.h index 0b14f7faa6..c0ba294145 100644 --- a/include/cantera/kinetics/InterfaceKinetics.h +++ b/include/cantera/kinetics/InterfaceKinetics.h @@ -1,6 +1,5 @@ /** * @file InterfaceKinetics.h - * @ingroup chemkinetics */ // This file is part of Cantera. See License.txt in the top-level directory or @@ -51,7 +50,7 @@ class ImplicitSurfChem; * kinetics operator. Nonexistent phases are deemed to be unstable by default, * but this can be changed. * - * @ingroup chemkinetics + * @ingroup kineticsmgr */ class InterfaceKinetics : public Kinetics { diff --git a/include/cantera/kinetics/InterfaceRate.h b/include/cantera/kinetics/InterfaceRate.h index 91a25dabbe..603feb3cc5 100644 --- a/include/cantera/kinetics/InterfaceRate.h +++ b/include/cantera/kinetics/InterfaceRate.h @@ -18,16 +18,6 @@ namespace Cantera class AnyMap; -/** - * @defgroup surfaceGroup Coverage-dependent rate parameterizations - * - * This section describes the parameterizations used to describe rate - * parameterization that involve interfaces. - * - * @ingroup chemkinetics - */ - - //! Data container holding shared data for reaction rate specification with interfaces /** * The data container InterfaceData holds precalculated data common to @@ -98,6 +88,7 @@ struct InterfaceData : public BlowersMaselData * The InterfaceRateBase class implements terms related to coverage only, which allows * for combinations with arbitrary rate parameterizations (for example Arrhenius and * BlowersMaselRate). + * @ingroup surfaceGroup */ class InterfaceRateBase { @@ -273,6 +264,7 @@ class InterfaceRateBase //! Base class for rate parameterizations that implement sticking coefficients /** * The StickingCoverage class enhances Coverage to accommodate sticking coefficients. + * @ingroup surfaceGroup */ class StickingCoverage : public InterfaceRateBase { @@ -369,6 +361,7 @@ class StickingCoverage : public InterfaceRateBase //! A class template for interface reaction rate specifications +//! @ingroup surfaceGroup template class InterfaceRate : public RateType, public InterfaceRateBase { @@ -455,11 +448,17 @@ class InterfaceRate : public RateType, public InterfaceRateBase } }; +//! Arrhenius-type interface reaction rate specifications +//! @ingroup surfaceGroup using InterfaceArrheniusRate = InterfaceRate; + +//! Blowers-Masel-type interface reaction rate specifications +//! @ingroup surfaceGroup using InterfaceBlowersMaselRate = InterfaceRate; //! A class template for interface sticking rate specifications +//! @ingroup surfaceGroup template class StickingRate : public RateType, public StickingCoverage { @@ -587,7 +586,12 @@ class StickingRate : public RateType, public StickingCoverage } }; +//! Arrhenius-type interface sticking rate specifications +//! @ingroup surfaceGroup using StickingArrheniusRate = StickingRate; + +//! Blowers-Masel-type interface sticking rate specifications +//! @ingroup surfaceGroup using StickingBlowersMaselRate = StickingRate; } diff --git a/include/cantera/kinetics/Kinetics.h b/include/cantera/kinetics/Kinetics.h index 43fe32acdc..66e6064175 100644 --- a/include/cantera/kinetics/Kinetics.h +++ b/include/cantera/kinetics/Kinetics.h @@ -26,7 +26,12 @@ class AnyMap; * @defgroup chemkinetics Chemical Kinetics */ +//! @defgroup reactionGroup Reactions and Reaction Rates +//! Classes for handling reactions and reaction rates. +//! @ingroup chemkinetics + //! @defgroup kineticsmgr Kinetics Managers +//! Classes implementing models for chemical kinetics. //! @section kinmodman Models and Managers //! //! A kinetics manager is a C++ class that implements a kinetics model; a @@ -93,6 +98,10 @@ class AnyMap; //! occupy the last 5 locations. //! @ingroup chemkinetics +//! @defgroup rateEvaluators Rate Evaluators +//! These classes are used to evaluate the rates of reactions. +//! @ingroup chemkinetics + //! Public interface for kinetics managers. /*! @@ -1414,8 +1423,6 @@ class Kinetics * * @return 0.0 if the stoichiometries are not multiples of one another * Otherwise, it returns the ratio of the stoichiometric coefficients. - * - * @ingroup kineticsmgr */ double checkDuplicateStoich(std::map& r1, std::map& r2) const; diff --git a/include/cantera/kinetics/KineticsFactory.h b/include/cantera/kinetics/KineticsFactory.h index e57366327d..8a9c386841 100644 --- a/include/cantera/kinetics/KineticsFactory.h +++ b/include/cantera/kinetics/KineticsFactory.h @@ -36,6 +36,9 @@ class KineticsFactory : public Factory static std::mutex kinetics_mutex; }; +//! @addtogroup kineticsmgr +//! @{ + /** * Create a new kinetics manager. * @deprecated To be removed after Cantera 3.0; superseded by newKinetics. @@ -47,9 +50,8 @@ Kinetics* newKineticsMgr(const string& model); */ shared_ptr newKinetics(const string& model); +//! Create a new kinetics manager, initialize it, and add reactions. /*! - * Create a new kinetics manager, initialize it, and add reactions - * * @param phases Vector of phases containing species which participate in * reactions, with the phase where the reactions occur (lowest-dimensional * phase) listed first. @@ -65,6 +67,7 @@ shared_ptr newKinetics(const vector>& phases, const AnyMap& rootNode=AnyMap(), shared_ptr soln={}); +//! @brief Create a new kinetics manager, initialize it, and add reactions. //! @see newKinetics(const vector>&, const AnyMap&, const AnyMap&, shared_ptr) //! @deprecated To be removed after Cantera 3.0; //! superseded by newKinetics() returning shared_ptr @@ -72,9 +75,8 @@ unique_ptr newKinetics(const std::vector& phases, const AnyMap& phaseNode, const AnyMap& rootNode=AnyMap()); +//! Create a new kinetics manager, initialize it, and add reactions. /*! - * Create a new kinetics manager, initialize it, and add reactions - * * @param phases Vector of phases containing species which participate in * reactions, with the phase where the reactions occur (lowest-dimensional * phase) listed first. @@ -100,7 +102,7 @@ unique_ptr newKinetics(const std::vector& phases, const std::string& phase_name); /*! - * Add reactions to a Kinetics object + * @brief Add reactions to a Kinetics object. * * @param kin The Kinetics object to be initialized * @param phaseNode Phase entry for the phase where the reactions occur. This @@ -112,6 +114,8 @@ unique_ptr newKinetics(const std::vector& phases, void addReactions(Kinetics& kin, const AnyMap& phaseNode, const AnyMap& rootNode=AnyMap()); +//! @} + } #endif diff --git a/include/cantera/kinetics/MultiRate.h b/include/cantera/kinetics/MultiRate.h index 1406a6e138..e83b1f94c5 100644 --- a/include/cantera/kinetics/MultiRate.h +++ b/include/cantera/kinetics/MultiRate.h @@ -16,6 +16,7 @@ namespace Cantera { //! A class template handling ReactionRate specializations. +//! @ingroup rateEvaluators template class MultiRate final : public MultiRateBase { diff --git a/include/cantera/kinetics/MultiRateBase.h b/include/cantera/kinetics/MultiRateBase.h index b132825b43..b0039f4080 100644 --- a/include/cantera/kinetics/MultiRateBase.h +++ b/include/cantera/kinetics/MultiRateBase.h @@ -22,6 +22,7 @@ class Kinetics; * Because this class has no template parameters, the Kinetics object can store all of * these rate coefficient evaluators as a `vector>`. All of * the actual implementation for this capability is done in the MultiRate class. + * @ingroup rateEvaluators */ class MultiRateBase { diff --git a/include/cantera/kinetics/PlogRate.h b/include/cantera/kinetics/PlogRate.h index a70eb4b096..0efb2ab980 100644 --- a/include/cantera/kinetics/PlogRate.h +++ b/include/cantera/kinetics/PlogRate.h @@ -71,6 +71,7 @@ struct PlogData : public ReactionData * the rate used in the interpolation formula is the sum of all the rates given * at that pressure. For pressures outside the given range, the rate expression * at the nearest pressure is used. + * @ingroup otherRateGroup */ class PlogRate final : public ReactionRate { diff --git a/include/cantera/kinetics/Reaction.h b/include/cantera/kinetics/Reaction.h index 1074c1cb65..2487e0845b 100644 --- a/include/cantera/kinetics/Reaction.h +++ b/include/cantera/kinetics/Reaction.h @@ -20,8 +20,6 @@ class ThirdBody; class ArrheniusRate; // @todo Remove after Cantera 3.0 class FalloffRate; // @todo Remove after Cantera 3.0 -//! @defgroup reactionGroup Reactions and reaction rates - //! Abstract base class which stores data about a reaction and its rate //! parameterization so that it can be added to a Kinetics object. //! @ingroup reactionGroup @@ -210,6 +208,7 @@ class Reaction //! A class for managing third-body efficiencies, including default values +//! @ingroup reactionGroup class ThirdBody { public: diff --git a/include/cantera/kinetics/ReactionData.h b/include/cantera/kinetics/ReactionData.h index 82a65bdad9..bf3a6ca96f 100644 --- a/include/cantera/kinetics/ReactionData.h +++ b/include/cantera/kinetics/ReactionData.h @@ -21,6 +21,7 @@ class Kinetics; //! Data container holding shared data used for ReactionRate calculation /** * The base class defines variables and methods used by all specializations. + * @ingroup reactionGroup */ struct ReactionData { diff --git a/include/cantera/kinetics/ReactionRate.h b/include/cantera/kinetics/ReactionRate.h index 8d6d370aeb..076753d48f 100644 --- a/include/cantera/kinetics/ReactionRate.h +++ b/include/cantera/kinetics/ReactionRate.h @@ -42,6 +42,7 @@ class Reaction; //! partners, associated `DataType` containers should implement the methods //! `perturbPressure(double deltaP)` and/or `perturbThirdBodies(double deltaM)`, //! which allow for the calculation of numerical derivatives. +//! @ingroup reactionGroup class ReactionRate { public: diff --git a/include/cantera/kinetics/ReactionRateDelegator.h b/include/cantera/kinetics/ReactionRateDelegator.h index a8e716d06d..68d6b27e0f 100644 --- a/include/cantera/kinetics/ReactionRateDelegator.h +++ b/include/cantera/kinetics/ReactionRateDelegator.h @@ -64,6 +64,7 @@ class ReactionDataDelegator : public Delegator, public ReactionData //! Delegate methods of the ReactionRate class to external functions //! //! @since New in Cantera 3.0 +//! @ingroup otherRateGroup class ReactionRateDelegator : public Delegator, public ReactionRate { public: diff --git a/include/cantera/kinetics/ReactionRateFactory.h b/include/cantera/kinetics/ReactionRateFactory.h index 88cb00ddcd..cc9c373e81 100644 --- a/include/cantera/kinetics/ReactionRateFactory.h +++ b/include/cantera/kinetics/ReactionRateFactory.h @@ -19,6 +19,32 @@ namespace Cantera class Kinetics; class Units; +/** + * @defgroup arrheniusGroup Arrhenius-type Parameterizations + * Classes implementing the standard Arrhenius rate parameterization and derived models. + * @ingroup reactionGroup + */ + +/** + * @defgroup falloffGroup Falloff Parameterizations + * Classes implementing fall-off in reaction rate constants due to intermolecular energy + * transfer and derived models. + * @ingroup reactionGroup + */ + +/** + * @defgroup surfaceGroup Interface Rate Parameterizations + * Classes implementing reaction rates that involve interfaces. + * @ingroup reactionGroup + */ + +/** + * @defgroup otherRateGroup Other Reaction Rate Parameterizations + * Classes implementing other reaction rate parameterizations. + * @ingroup reactionGroup + */ + + /** * Factory class to construct reaction rate calculators. * The reaction factory is accessed through the static method factory: @@ -26,8 +52,6 @@ class Units; * @code * Rate* f = ReactionRateFactory::factory()->newReactionRate(type, c) * @endcode - * - * @ingroup reactionGroup */ class ReactionRateFactory : public Factory @@ -53,6 +77,8 @@ class ReactionRateFactory static std::mutex rate_mutex; }; +//! @addtogroup reactionGroup +//! @{ //! Create a new empty ReactionRate object /*! @@ -75,5 +101,7 @@ shared_ptr newReactionRate( */ shared_ptr newReactionRate(const AnyMap& rate_node); +//! @} + } #endif diff --git a/include/cantera/kinetics/StoichManager.h b/include/cantera/kinetics/StoichManager.h index cc6b544c96..63d3961626 100644 --- a/include/cantera/kinetics/StoichManager.h +++ b/include/cantera/kinetics/StoichManager.h @@ -119,6 +119,8 @@ namespace Cantera * non-zero entries of the sparse derivative matrix of the reaction rate-of-progress * vector, which itself is evaluated by the derivatives() method. The scale() method is * used to multiply rop entries by reaction order and a user-supplied factor. + * + * @ingroup rateEvaluators */ /** diff --git a/include/cantera/kinetics/ThirdBodyCalc.h b/include/cantera/kinetics/ThirdBodyCalc.h index d404a85ef1..fac1a6b8d1 100644 --- a/include/cantera/kinetics/ThirdBodyCalc.h +++ b/include/cantera/kinetics/ThirdBodyCalc.h @@ -15,6 +15,7 @@ namespace Cantera //! Calculate and apply third-body effects on reaction rates, including non- //! unity third-body efficiencies. +//! @ingroup rateEvaluators class ThirdBodyCalc { public: From 7e18ebf40467f52158390e574b14d7cdccda6ca7 Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Fri, 7 Jul 2023 13:26:07 -0600 Subject: [PATCH 4/8] [docs] Update doxygen numerics groupings --- include/cantera/base/Array.h | 2 ++ include/cantera/base/global.h | 4 ++-- include/cantera/base/utilities.h | 15 ++++++++++++--- include/cantera/numerics/BandMatrix.h | 2 ++ include/cantera/numerics/DenseMatrix.h | 16 ++++++++++------ include/cantera/numerics/Func1.h | 1 + include/cantera/numerics/FuncEval.h | 4 ++++ include/cantera/numerics/GeneralMatrix.h | 3 ++- include/cantera/numerics/eigen_dense.h | 7 +++++++ include/cantera/numerics/eigen_sparse.h | 1 + include/cantera/numerics/funcs.h | 11 +++++++++++ include/cantera/numerics/polyfit.h | 1 + 12 files changed, 55 insertions(+), 12 deletions(-) diff --git a/include/cantera/base/Array.h b/include/cantera/base/Array.h index f25e0015c6..e70b01deab 100644 --- a/include/cantera/base/Array.h +++ b/include/cantera/base/Array.h @@ -25,6 +25,8 @@ namespace Cantera * J(i,j) = data_start + index * i = row * j = column + * + * @ingroup matrices */ class Array2D { diff --git a/include/cantera/base/global.h b/include/cantera/base/global.h index a4cf06d802..f3aab509ab 100644 --- a/include/cantera/base/global.h +++ b/include/cantera/base/global.h @@ -4,8 +4,6 @@ * inputfiles, logs, textlogs, (see \ref inputfiles, \ref logs, and * \ref textlogs). * - * @ingroup utils - * * These functions store some parameters in global storage that are accessible * at all times from the calling application. Contains module definitions for * - inputfiles (see \ref inputfiles) @@ -283,6 +281,7 @@ void setLogger(Logger* logwriter); void printStackTraceOnSegfault(); //! Clip *value* such that lower <= value <= upper +//! @ingroup mathTemplates template inline T clip(const T& value, const T& lower, const T& upper) { @@ -290,6 +289,7 @@ inline T clip(const T& value, const T& lower, const T& upper) } //! Sign of a number. Returns -1 if x < 0, 1 if x > 0 and 0 if x == 0. +//! @ingroup mathTemplates template int sign(T x) { return (T(0) < x) - (x < T(0)); } diff --git a/include/cantera/base/utilities.h b/include/cantera/base/utilities.h index cbaa486a36..bd82f33583 100644 --- a/include/cantera/base/utilities.h +++ b/include/cantera/base/utilities.h @@ -1,17 +1,19 @@ /** * @file utilities.h - * Various templated functions that carry out common vector - * operations (see \ref utils). + * Various templated functions that carry out common vector and polynomial operations + * (see \ref mathTemplates). */ // This file is part of Cantera. See License.txt in the top-level directory or // at https://cantera.org/license.txt for license and copyright information. /** - * @defgroup utils Templated Utility Functions + * @defgroup mathTemplates Templated Array and Polynomial Operations * * These are templates to perform various simple operations on arrays. Note that * the compiler will inline these, so using them carries no performance penalty. + * + * @ingroup numerics */ #ifndef CT_UTILITIES_H @@ -22,6 +24,10 @@ namespace Cantera { +/** @addtogroup mathTemplates + * @{ + */ + //! Templated Inner product of two vectors of length 4. /*! * If either \a x or \a y has length greater than 4, only the first 4 elements @@ -163,6 +169,8 @@ R poly3(D x, R* c) return (((c[3]*x + c[2])*x + c[1])*x + c[0]); } +/** @}*/ + //! Check to see that a number is finite (not NaN, +Inf or -Inf) void checkFinite(const double tmp); @@ -187,6 +195,7 @@ const U& getValue(const std::map& m, const T& key, const U& default_val) { } //! Get the size of a container, cast to a signed integer type +//! @ingroup mathTemplates template U len(const T& container) { return static_cast(container.size()); diff --git a/include/cantera/numerics/BandMatrix.h b/include/cantera/numerics/BandMatrix.h index 0754522fd0..1441be90a2 100644 --- a/include/cantera/numerics/BandMatrix.h +++ b/include/cantera/numerics/BandMatrix.h @@ -30,6 +30,8 @@ namespace Cantera * This class is a derived class of the base class GeneralMatrix. However, * within the oneD directory, the class is used as is, without reference to the * GeneralMatrix base type. + * + * @ingroup matrices */ class BandMatrix : public GeneralMatrix { diff --git a/include/cantera/numerics/DenseMatrix.h b/include/cantera/numerics/DenseMatrix.h index 8172a24427..8655acc124 100644 --- a/include/cantera/numerics/DenseMatrix.h +++ b/include/cantera/numerics/DenseMatrix.h @@ -18,12 +18,16 @@ namespace Cantera { /** - * @defgroup numerics Numerical Utilities within Cantera - * - * Cantera contains some capabilities for solving nonlinear equations and - * integrating both ODE and DAE equation systems in time. This section describes - * these capabilities. + * @defgroup numerics Numerical Utilities * + * @details Cantera contains some capabilities for solving nonlinear equations and + * integrating both ODE and DAE equation systems in time. + */ + +/** + * @defgroup matrices Matrix Handling + * Classes and methods implementing matrix operations. + * @ingroup numerics */ //! A class for full (non-sparse) matrices with Fortran-compatible data storage, @@ -45,7 +49,7 @@ namespace Cantera * m_printLevel. The default is for no reporting. If m_printLevel is nonzero, * the error condition is reported to Cantera's log file. * - * @ingroup numerics + * @ingroup matrices */ class DenseMatrix : public Array2D { diff --git a/include/cantera/numerics/Func1.h b/include/cantera/numerics/Func1.h index 63fbbd3b2e..7df5aa66ca 100644 --- a/include/cantera/numerics/Func1.h +++ b/include/cantera/numerics/Func1.h @@ -43,6 +43,7 @@ class TimesConstant1; //! Functors implement functions of a single variable \f$ f(x) \f$. //! Functor objects can be combined to form compound expressions, which allows for //! the implementation of generic mathematical expressions. +//! @ingroup numerics //! @defgroup func1simple Simple Functors //! Simple functors implement standard mathematical expressions with a single diff --git a/include/cantera/numerics/FuncEval.h b/include/cantera/numerics/FuncEval.h index 63f4b08c50..f29ddc99d1 100644 --- a/include/cantera/numerics/FuncEval.h +++ b/include/cantera/numerics/FuncEval.h @@ -15,6 +15,10 @@ namespace Cantera { +/** + * @defgroup odeGroup ODE and DAE Function Utilities +*/ + /** * Virtual base class for ODE/DAE right-hand-side function evaluators. * Classes derived from FuncEval evaluate the right-hand-side function diff --git a/include/cantera/numerics/GeneralMatrix.h b/include/cantera/numerics/GeneralMatrix.h index 1df8f32c12..d69dd0b7fa 100644 --- a/include/cantera/numerics/GeneralMatrix.h +++ b/include/cantera/numerics/GeneralMatrix.h @@ -1,7 +1,7 @@ /** * @file GeneralMatrix.h * Declarations for the class GeneralMatrix which is a virtual base class for matrices handled by solvers - * (see class \ref numerics and \link Cantera::GeneralMatrix GeneralMatrix\endlink). + * (see class \ref matrices and \link Cantera::GeneralMatrix GeneralMatrix\endlink). */ // This file is part of Cantera. See License.txt in the top-level directory or @@ -18,6 +18,7 @@ namespace Cantera { //! Generic matrix +//! @ingroup matrices class GeneralMatrix { public: diff --git a/include/cantera/numerics/eigen_dense.h b/include/cantera/numerics/eigen_dense.h index da3a6772cc..e8ba661aaa 100644 --- a/include/cantera/numerics/eigen_dense.h +++ b/include/cantera/numerics/eigen_dense.h @@ -18,12 +18,19 @@ namespace Cantera { +/** @addtogroup matrices + * @{ + */ + typedef Eigen::Map MappedMatrix; typedef Eigen::Map ConstMappedMatrix; typedef Eigen::Map MappedVector; typedef Eigen::Map ConstMappedVector; typedef Eigen::Map MappedRowVector; typedef Eigen::Map ConstMappedRowVector; + +/** @}*/ + } #endif diff --git a/include/cantera/numerics/eigen_sparse.h b/include/cantera/numerics/eigen_sparse.h index c9660e91ff..ecb83722c7 100644 --- a/include/cantera/numerics/eigen_sparse.h +++ b/include/cantera/numerics/eigen_sparse.h @@ -17,6 +17,7 @@ namespace Cantera { +//! @ingroup matrices typedef std::vector> SparseTriplets; } diff --git a/include/cantera/numerics/funcs.h b/include/cantera/numerics/funcs.h index d8b0e4d04f..16ccd2f351 100644 --- a/include/cantera/numerics/funcs.h +++ b/include/cantera/numerics/funcs.h @@ -15,6 +15,13 @@ namespace Cantera { +/** + * @defgroup mathUtils Numerical Integration and Interpolation + * Collection of numerical utility functions for integration, interpolation and data + * fitting. + * @ingroup numerics +*/ + //! Linearly interpolate a function defined on a discrete grid. /*! * Vector xpts contains a monotonic sequence of grid points, and vector fpts @@ -26,6 +33,7 @@ namespace Cantera * @param xpts value of the grid points * @param fpts value of the interpolant at the grid points * @returns the value of of the interpolated function at x. + * @ingroup mathUtils */ doublereal linearInterp(doublereal x, const vector_fp& xpts, const vector_fp& fpts); @@ -38,6 +46,7 @@ doublereal linearInterp(doublereal x, const vector_fp& xpts, * * @param f vector of function value * @param x vector of function coordinate + * @ingroup mathUtils */ double trapezoidal(const Eigen::ArrayXd& f, const Eigen::ArrayXd& x); @@ -52,6 +61,7 @@ double trapezoidal(const Eigen::ArrayXd& f, const Eigen::ArrayXd& x); * * @param f vector of function value * @param x vector of function coordinate + * @ingroup mathUtils */ double simpson(const Eigen::ArrayXd& f, const Eigen::ArrayXd& x); @@ -64,6 +74,7 @@ double simpson(const Eigen::ArrayXd& f, const Eigen::ArrayXd& x); * @param method method name * @param f vector of function value * @param x vector of function coordinate + * @ingroup mathUtils */ double numericalQuadrature(const std::string& method, const Eigen::ArrayXd& f, diff --git a/include/cantera/numerics/polyfit.h b/include/cantera/numerics/polyfit.h index 03a27ae4a4..5c40bc2992 100644 --- a/include/cantera/numerics/polyfit.h +++ b/include/cantera/numerics/polyfit.h @@ -28,6 +28,7 @@ namespace Cantera * @param[out] p Array of polynomial coefficients, starting with the constant * term. Length *deg+1*. * @returns the root mean squared error of the fit at the input points. + * @ingroup mathUtils */ double polyfit(size_t n, size_t deg, const double* x, const double* y, const double* w, double* p); From b30b7d647a9e13c8bb6b4d5e0082b789774c6d84 Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Fri, 7 Jul 2023 14:27:06 -0600 Subject: [PATCH 5/8] [docs] Fix doxygen documentation of physical constants --- include/cantera/base/ct_defs.h | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/include/cantera/base/ct_defs.h b/include/cantera/base/ct_defs.h index a2d5218d5b..d6dd589ddb 100644 --- a/include/cantera/base/ct_defs.h +++ b/include/cantera/base/ct_defs.h @@ -47,13 +47,20 @@ using std::function; using std::pair; /*! - * All physical constants are stored here. - * * @defgroup physConstants Physical Constants + * @brief Physical constants used by %Cantera. + * * %Cantera uses the MKS system of units. The unit for moles * is defined to be the kmol. All values of physical constants * are consistent with the 2018 CODATA recommendations. * @ingroup globalData + */ + +//! @addtogroup physConstants +//! @{ + +/** + * @name Numerical Constants * @{ */ @@ -66,8 +73,8 @@ const double Sqrt2 = 1.41421356237309504880; //! @} //! @name Defined Constants //! -//! These constants are defined by CODATA to have a particular value. -//! https://physics.nist.gov/cuu/Constants/index.html +//! These constants are defined by CODATA to have a particular value; see +//! [NIST Reference on Constants, Units, and Uncertainty](https://physics.nist.gov/cuu/Constants/index.html). //! @{ //! Avogadro's Number \f$ N_{\mathrm{A}} \f$ [number/kmol] @@ -130,6 +137,9 @@ const double permeability_0 = 2 * fineStructureConstant * Planck / (ElectronChar const double epsilon_0 = 1.0 / (lightSpeed * lightSpeed * permeability_0); //! @} + +//! @} + //! @name Thermodynamic Equilibrium Constraints //! //! Integer numbers representing pairs of thermodynamic variables From f44937084edf3494e43fc3fc5c733a8497213e54 Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Fri, 7 Jul 2023 16:35:32 -0600 Subject: [PATCH 6/8] [docs] Restructure doxygen error & diagnostics grouping --- include/cantera/base/ExternalLogger.h | 2 +- include/cantera/base/NoExitLogger.h | 2 +- include/cantera/base/ctexceptions.h | 26 +++++--- include/cantera/base/global.h | 87 +++++++++++++++++++-------- include/cantera/base/logger.h | 4 +- src/base/application.h | 20 +++--- 6 files changed, 93 insertions(+), 48 deletions(-) diff --git a/include/cantera/base/ExternalLogger.h b/include/cantera/base/ExternalLogger.h index ea35481061..1232861477 100644 --- a/include/cantera/base/ExternalLogger.h +++ b/include/cantera/base/ExternalLogger.h @@ -9,7 +9,7 @@ namespace Cantera { //! Logger that delegates to an external source via a callback to produce log output. -//! @ingroup textlogs +//! @ingroup logGroup class ExternalLogger : public Logger { public: diff --git a/include/cantera/base/NoExitLogger.h b/include/cantera/base/NoExitLogger.h index 1eb703e6e1..bbed4f93e3 100644 --- a/include/cantera/base/NoExitLogger.h +++ b/include/cantera/base/NoExitLogger.h @@ -10,7 +10,7 @@ namespace Cantera { //! Logger that doesn't exit when an error is thrown. -//! @ingroup textlogs +//! @ingroup logGroup class NoExitLogger : public Logger { public: NoExitLogger() {} diff --git a/include/cantera/base/ctexceptions.h b/include/cantera/base/ctexceptions.h index 0a945aee63..aef49ba02e 100644 --- a/include/cantera/base/ctexceptions.h +++ b/include/cantera/base/ctexceptions.h @@ -2,7 +2,7 @@ * @file ctexceptions.h * Definitions for the classes that are * thrown when %Cantera experiences an error condition - * (also contains errorhandling module text - see \ref errorhandling). + * (also contains errorhandling module text - see \ref errGroup). */ // This file is part of Cantera. See License.txt in the top-level directory or @@ -18,11 +18,14 @@ namespace Cantera { +/** + * @defgroup debugGroup Errors & Diagnostics +*/ + /*! - * @defgroup errorhandling Error Handling + * @defgroup errGroup Errors * - * \brief These classes and related functions are used to handle errors and - * unknown events within Cantera. + * @brief Handling of errors and unknown events within %Cantera. * * The general idea is that exceptions are thrown using the common base class * called CanteraError. Derived types of CanteraError characterize what type of @@ -47,6 +50,7 @@ namespace Cantera * is thrown, with descriptive information indicating where the error occurred. * The Assert* checks are skipped if the NDEBUG preprocessor symbol is defined, * for example with the compiler option -DNDEBUG. + * @ingroup debugGroup */ @@ -56,7 +60,7 @@ namespace Cantera * from std::exception so that normal error handling operations from * applications may automatically handle the errors in their own way. * - * @ingroup errorhandling + * @ingroup errGroup */ class CanteraError : public std::exception { @@ -126,7 +130,7 @@ class CanteraError : public std::exception * This error is thrown if a supplied length to a vector supplied to Cantera is * too small. * - * @ingroup errorhandling + * @ingroup errGroup */ class ArraySizeError : public CanteraError { @@ -156,7 +160,7 @@ class ArraySizeError : public CanteraError //! An array index is out of range. /*! - * @ingroup errorhandling + * @ingroup errGroup */ class IndexError : public CanteraError { @@ -187,6 +191,7 @@ class IndexError : public CanteraError }; //! An error indicating that an unimplemented function has been called +//! @ingroup errGroup class NotImplementedError : public CanteraError { public: @@ -238,7 +243,7 @@ class NotImplementedError : public CanteraError * * @param expr Boolean expression that must be true * - * @ingroup errorhandling + * @ingroup errGroup */ #ifndef AssertTrace # define AssertTrace(expr) ((expr) ? (void) 0 : throw CanteraError(STR_TRACE, std::string("failed assert: ") + #expr)) @@ -252,7 +257,7 @@ class NotImplementedError : public CanteraError * @param expr Boolean expression that must be true * @param procedure Character string or std:string expression indicating the * procedure where the assertion failed - * @ingroup errorhandling + * @ingroup errGroup */ #ifndef AssertThrow # define AssertThrow(expr, procedure) ((expr) ? (void) 0 : throw CanteraError(procedure, std::string("failed assert: ") + #expr)) @@ -269,7 +274,7 @@ class NotImplementedError : public CanteraError * Additional arguments are passed on to the constructor for CanteraError to * generate a formatted error message. * - * @ingroup errorhandling + * @ingroup errGroup */ #ifndef AssertThrowMsg # define AssertThrowMsg(expr, procedure, ...) ((expr) ? (void) 0 : throw CanteraError(procedure + std::string(":\nfailed assert: \"") + std::string(#expr) + std::string("\""), __VA_ARGS__)) @@ -278,6 +283,7 @@ class NotImplementedError : public CanteraError #endif //! Throw an exception if the specified exception is not a finite number. +//! @ingroup errGroup #ifndef AssertFinite # define AssertFinite(expr, procedure, ...) AssertThrowMsg(expr < BigNumber && expr > -BigNumber, procedure, __VA_ARGS__) #endif diff --git a/include/cantera/base/global.h b/include/cantera/base/global.h index f3aab509ab..eca3d17114 100644 --- a/include/cantera/base/global.h +++ b/include/cantera/base/global.h @@ -1,14 +1,12 @@ /** * @file global.h * This file contains definitions for utility functions and text for modules, - * inputfiles, logs, textlogs, (see \ref inputfiles, \ref logs, and - * \ref textlogs). + * inputfiles and logging, (see \ref inputfiles, and \ref logGroup). * * These functions store some parameters in global storage that are accessible * at all times from the calling application. Contains module definitions for * - inputfiles (see \ref inputfiles) - * - logs (see \ref logs) - * - textlogs (see \ref textlogs) + * - text logs (see \ref logGroup) */ // This file is part of Cantera. See License.txt in the top-level directory or @@ -85,11 +83,6 @@ void loadExtensions(const AnyMap& node); //! @copydoc Application::searchPythonVersions void searchPythonVersions(const string& versions); -//! Returns `true` if Cantera was loaded as a shared library in the current -//! application. Returns `false` if it was statically linked. -//! @since New in Cantera 3.0 -bool usingSharedLibrary(); - //! Delete and free all memory associated with the application /*! * Delete all global data. It should be called at the end of the @@ -100,37 +93,56 @@ void appdelete(); //! @copydoc Application::thread_complete void thread_complete(); -//! Returns the Cantera version. This function when needing to access the version from a -//! library, rather than the `CANTERA_VERSION` macro that is available at compile time. +//! @defgroup globalSettings Global Cantera Settings +//! @brief Functions for accessing global %Cantera settings. +//! @ingroup globalData + +//! @addtogroup globalSettings +//! @{ + +//! Returns `true` if %Cantera was loaded as a shared library in the current +//! application. Returns `false` if it was statically linked. +//! @since New in Cantera 3.0 +bool usingSharedLibrary(); + +//! @name Cantera Version Information +//! @{ + +//! Returns the %Cantera version. This function is used to access the version from a +//! library, rather than the \c CANTERA_VERSION macro that is available at compile time. //! @since New in Cantera 3.0 string version(); -//! Returns the hash of the git commit from which Cantera was compiled, if known +//! Returns the hash of the git commit from which %Cantera was compiled, if known std::string gitCommit(); -//! Returns true if Cantera was compiled in debug mode. Used for handling some cases +//! @} + +//! Returns true if %Cantera was compiled in debug mode. Used for handling some cases //! where behavior tested in the test suite changes depending on whether the `NDEBUG` //! preprocessor macro is defined. bool debugModeEnabled(); -//! Returns true if Cantera was compiled with C++ HDF5 support. +//! Returns true if %Cantera was compiled with C++ \c HDF5 support. //! @since New in Cantera 3.0. bool usesHDF5(); +//! @} + /*! - * @defgroup logs Diagnostic Output + * @defgroup logGroup Logging + * @brief Logging and generation of 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 a set of procedures for this purpose designed to write text messages + * Cantera defines a set of procedures for this purpose designed to write text messages * to the screen to document the progress of a complex calculation, such as a * flame simulation. + * @ingroup debugGroup */ -/*! - * @defgroup textlogs Writing messages to the screen - * @ingroup logs - */ +//! @addtogroup logGroup +//! @{ //! @copydoc Application::Messages::writelog(const std::string&) void writelog_direct(const std::string& msg); @@ -152,7 +164,6 @@ inline void debuglog(const std::string& msg, int loglevel) //! 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 template void writelog(const std::string& fmt, const Args&... args) { if (sizeof...(args) == 0) { @@ -172,7 +183,6 @@ void writelog(const std::string& fmt, const Args&... args) { * * @param fmt c format string for the following arguments * @param args arguments used to interpolate the format string - * @ingroup textlogs */ template void writelogf(const char* fmt, const Args& ... args) { @@ -185,9 +195,20 @@ void writelogendl(); void writeline(char repeat, size_t count, bool endl_after=true, bool endl_before=false); +//! @} End of logging group + +//! @defgroup warnGroup Warnings +//! @ingroup debugGroup +//! @brief Warnings raised by %Cantera +//! @{ + +//! @cond + //! helper function passing deprecation warning to global handler void _warn_deprecated(const std::string& method, const std::string& extra=""); +//! @endcond + //! Print a deprecation warning raised from *method*. /*! * @see Application::warn_deprecated @@ -205,13 +226,14 @@ void warn_deprecated(const std::string& method, const std::string& msg, } } -//! @copydoc Application::suppress_deprecation_warnings -void suppress_deprecation_warnings(); +//! @cond //! helper function passing generic warning to global handler void _warn(const std::string& warning, const std::string& method, const std::string& extra); +//! @endcond + //! Print a generic warning raised from *method*. /*! * @see Application::warn @@ -246,6 +268,17 @@ void warn_user(const std::string& method, const std::string& msg, } } +//! @} End of warnings group + +//! @addtogroup globalSettings +//! @{ + +//! @name Global Warning Settings +//! @{ + +//! @copydoc Application::suppress_deprecation_warnings +void suppress_deprecation_warnings(); + //! @copydoc Application::make_deprecation_warnings_fatal void make_deprecation_warnings_fatal(); @@ -264,13 +297,18 @@ void suppress_warnings(); //! @copydoc Application::warnings_suppressed bool warnings_suppressed(); +//! @} End of warning settings + //! @copydoc Application::use_legacy_rate_constants void use_legacy_rate_constants(bool legacy=true); //! @copydoc Application::legacy_rate_constants_used bool legacy_rate_constants_used(); +// @} End of globalSettings group + //! @copydoc Application::Messages::setLogger +//! @ingroup logGroup void setLogger(Logger* logwriter); //! Enables printing a stacktrace to `std::err` if a segfault occurs. The Boost @@ -278,6 +316,7 @@ void setLogger(Logger* logwriter); //! and risks deadlocking. However, it can be useful for debugging and is therefore //! enabled when running tests. //! @since New in Cantera 3.0 +//! @ingroup globalSettings void printStackTraceOnSegfault(); //! Clip *value* such that lower <= value <= upper diff --git a/include/cantera/base/logger.h b/include/cantera/base/logger.h index 409507aa46..65d6a57ee0 100644 --- a/include/cantera/base/logger.h +++ b/include/cantera/base/logger.h @@ -1,7 +1,7 @@ /** * @file logger.h * Header for Base class for 'loggers' that write text messages to log files - * (see \ref textlogs and class \link Cantera::Logger Logger\endlink). + * (see \ref logGroup and class \link Cantera::Logger Logger\endlink). */ // This file is part of Cantera. See License.txt in the top-level directory or @@ -35,7 +35,7 @@ namespace Cantera //! See the files Cantera/python/src/pylogger.h and //! Cantera/matlab/cantera/private/mllogger.h for examples of //! deriving logger classes. -//! @ingroup textlogs +//! @ingroup logGroup //! class Logger { diff --git a/src/base/application.h b/src/base/application.h index b37b8bdd83..d971d1f5e7 100644 --- a/src/base/application.h +++ b/src/base/application.h @@ -35,8 +35,8 @@ namespace Cantera * here. At most one instance is created, and it is not destroyed until the * process terminates. * - * @ingroup textlogs * @ingroup globalData + * @ingroup debugGroup */ class Application { @@ -60,13 +60,13 @@ class Application * * If only one argument is specified, that string is used as the * entire message. - * @ingroup errorhandling + * @ingroup errGroup */ void addError(const std::string& r, const std::string& msg=""); //! Return the number of errors that have been encountered so far. /*! - * @ingroup errorhandling + * @ingroup errGroup */ int getErrorCount(); @@ -76,7 +76,7 @@ class Application * Application class. This routine eliminates the last exception to be * added to that stack. * - * @ingroup errorhandling + * @ingroup errGroup */ void popError(); @@ -85,7 +85,7 @@ class Application * This routine will retrieve the last error message and return it in * the return string. * - * @ingroup errorhandling + * @ingroup errGroup */ std::string lastErrorMessage(); @@ -99,7 +99,7 @@ class Application * * @param f ostream which will receive the error messages * - * @ingroup errorhandling + * @ingroup errGroup */ void getErrors(std::ostream& f); @@ -110,7 +110,7 @@ class Application * class. This routine writes out all of the error messages and then * clears them from internal storage. * - * @ingroup errorhandling + * @ingroup errGroup */ void logErrors(); @@ -125,7 +125,7 @@ class Application * standard output stream. * * @param msg c++ string to be written to the screen - * @ingroup textlogs + * @ingroup logGroup */ void writelog(const std::string& msg); @@ -136,7 +136,7 @@ class Application /*! * @param warning String specifying type of warning; see Logger::warn() * @param msg String to be written to the screen - * @ingroup textlogs + * @ingroup logGroup */ void warnlog(const std::string& warning, const std::string& msg); @@ -147,7 +147,7 @@ class Application * * @param logwriter Pointer to a logger object * @see Logger. - * @ingroup textlogs + * @ingroup logGroup */ void setLogger(Logger* logwriter); From 29cbcb28679c517a3528550de0ba0abdf908fb31 Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Fri, 7 Jul 2023 16:49:45 -0600 Subject: [PATCH 7/8] [docs] Increate DOT_GRAPH_MAX_NODES --- doc/doxygen/Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile index bbc362224e..b5cc3e8231 100644 --- a/doc/doxygen/Doxyfile +++ b/doc/doxygen/Doxyfile @@ -2508,7 +2508,7 @@ PLANTUML_INCLUDE_PATH = # Minimum value: 0, maximum value: 10000, default value: 50. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_GRAPH_MAX_NODES = 50 +DOT_GRAPH_MAX_NODES = 100 # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs # generated by dot. A depth value of 3 means that only nodes reachable from the From 3b64999aa82ecf1d9710f74f88c0635bca9b9bb6 Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Fri, 7 Jul 2023 15:02:14 -0600 Subject: [PATCH 8/8] [docs] Switch to markdown mainfile Supported for doxygen 1.8.3 and later (released 2012) --- doc/doxygen/Cantera.txt | 6 ------ doc/doxygen/Doxyfile | 5 +++-- doc/doxygen/mainpage.md | 23 +++++++++++++++++++++++ include/cantera/base/Solution.h | 4 ++-- include/cantera/zeroD/ReactorBase.h | 7 ++++--- 5 files changed, 32 insertions(+), 13 deletions(-) delete mode 100644 doc/doxygen/Cantera.txt create mode 100644 doc/doxygen/mainpage.md diff --git a/doc/doxygen/Cantera.txt b/doc/doxygen/Cantera.txt deleted file mode 100644 index 63c13a8f8f..0000000000 --- a/doc/doxygen/Cantera.txt +++ /dev/null @@ -1,6 +0,0 @@ -/** -\mainpage Cantera C++ Reference - -Use the menu at the top to view detailed documentation of the code. - -*/ diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile index b5cc3e8231..269b94c072 100644 --- a/doc/doxygen/Doxyfile +++ b/doc/doxygen/Doxyfile @@ -866,7 +866,8 @@ INPUT = src/base \ src/transport \ src/zeroD \ include \ - doc/doxygen + doc/doxygen \ + doc/doxygen/mainpage.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -1027,7 +1028,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = mainpage.md #--------------------------------------------------------------------------- # Configuration options related to source browsing diff --git a/doc/doxygen/mainpage.md b/doc/doxygen/mainpage.md new file mode 100644 index 0000000000..deb690e11d --- /dev/null +++ b/doc/doxygen/mainpage.md @@ -0,0 +1,23 @@ +# %Cantera C++ Reference + +Use the menu at the top to view detailed documentation of the code, or use the +following shortcuts: + +* Overview of [**Cantera Modules**](modules.html) +* Index of [**Cantera Classes**](classes.html) + +A topical overview is provided as follows: + +* @ref compobj (interface to %Cantera core objects) +* @ref thermoprops (temperature, pressure, energy, ...) +* @ref chemkinetics (reactions, rates of progress, reaction path analysis, ...) +* @ref tranprops (diffusion, viscosity, thermal conductivity, ...) +* @ref ZeroD (reactors, walls, flow devices, ...) +* @ref onedim (flames, flow domains, boundaries, ...) +* @ref physConstants (universal constants, built into %Cantera for convenience) + +For fundamental scientific theory used for the implementation of %Cantera, refer to the +[Cantera Science Section](https://cantera.org/science/index.html) of the +[Cantera Website](https://cantera.org). + +The %Cantera source code is hosted on [GitHub](https://github.com/Cantera/cantera). diff --git a/include/cantera/base/Solution.h b/include/cantera/base/Solution.h index c0c3de68e6..4b8dcddcc0 100644 --- a/include/cantera/base/Solution.h +++ b/include/cantera/base/Solution.h @@ -17,8 +17,8 @@ class Kinetics; class Transport; class ExternalHandle; -//! @defgroup compobj Composite Objects -//! Composite objects create a high-level interface to Cantera's core objects. +//! @defgroup compobj Objects Representing Phases +//! High-level interface to %Cantera's core objects. //! A container class for chemically-reacting solutions. /*! diff --git a/include/cantera/zeroD/ReactorBase.h b/include/cantera/zeroD/ReactorBase.h index 81591d848e..71b5e15237 100644 --- a/include/cantera/zeroD/ReactorBase.h +++ b/include/cantera/zeroD/ReactorBase.h @@ -15,9 +15,10 @@ namespace Cantera //! @defgroup ZeroD Zero-dimensional reactor networks //! -//! See https://cantera.org/science/reactors.html for a description of the governing -//! equations for specific reactor types and the methods used for solving networks of -// interconnected reactors. +//! See the [Reactor Science](https://cantera.org/science/reactors/reactors.html) +//! section of the %Cantera website for a description of the governing equations for +//! specific reactor types and the methods used for solving networks of interconnected +//! reactors. class FlowDevice; class WallBase;