From cd03c905a0e83636dba747315f2e5d42ab1189e0 Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Fri, 7 Jul 2023 08:39:12 -0600 Subject: [PATCH] [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 | 8 +++++ 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 | 30 ++++++++++++++++++- include/cantera/kinetics/StoichManager.h | 2 ++ include/cantera/kinetics/ThirdBodyCalc.h | 1 + 22 files changed, 80 insertions(+), 42 deletions(-) diff --git a/include/cantera/kinetics/Arrhenius.h b/include/cantera/kinetics/Arrhenius.h index d598045a394..f7812a693de 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 cb0e7656aed..39138a45e19 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 1a923290a1a..ec9e4485e8d 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 02353b16f3e..1f1a39d7c05 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 048f9a88eeb..b2dd471c47b 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 11e2abe5e3f..3827965650a 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 463955aae93..0dd23a305dc 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 19cedfca00d..8cde1cf9206 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 0b14f7faa6b..c0ba2941459 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 91a25dabbeb..603feb3cc53 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 43fe32acdc6..66e6064175d 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 e57366327d6..9d29e44ac42 100644 --- a/include/cantera/kinetics/KineticsFactory.h +++ b/include/cantera/kinetics/KineticsFactory.h @@ -17,6 +17,7 @@ namespace Cantera /** * Factory for kinetics managers. + * @ingroup kineticsmgr */ class KineticsFactory : public Factory { @@ -39,11 +40,13 @@ class KineticsFactory : public Factory /** * Create a new kinetics manager. * @deprecated To be removed after Cantera 3.0; superseded by newKinetics. + * @ingroup kineticsmgr */ Kinetics* newKineticsMgr(const string& model); /** * Create a new Kinetics instance. + * @ingroup kineticsmgr */ shared_ptr newKinetics(const string& model); @@ -59,6 +62,7 @@ shared_ptr newKinetics(const string& model); * @param rootNode The root node of the file containing the phase definition, * which will be treated as the default source for reactions * @param soln The Solution object that this Kinetics object is being added to. + * @ingroup kineticsmgr */ shared_ptr newKinetics(const vector>& phases, const AnyMap& phaseNode, @@ -68,6 +72,7 @@ shared_ptr newKinetics(const vector>& phases, //! @see newKinetics(const vector>&, const AnyMap&, const AnyMap&, shared_ptr) //! @deprecated To be removed after Cantera 3.0; //! superseded by newKinetics() returning shared_ptr +//! @ingroup kineticsmgr unique_ptr newKinetics(const std::vector& phases, const AnyMap& phaseNode, const AnyMap& rootNode=AnyMap()); @@ -87,6 +92,7 @@ unique_ptr newKinetics(const std::vector& phases, * @since Starting with Cantera 3.0, if the reacting phase is not the first item in the * `phases` vector, a deprecation warning will be issued. In Cantera 3.1, this * warning will become an error. + * @ingroup kineticsmgr */ shared_ptr newKinetics(const vector>& phases, const string& filename, @@ -95,6 +101,7 @@ shared_ptr newKinetics(const vector>& phases, //! @copydoc newKinetics(const vector>&, const string&, const string&) //! @deprecated To be removed after Cantera 3.0; //! superseded by newKinetics() returning shared_ptr +//! @ingroup kineticsmgr unique_ptr newKinetics(const std::vector& phases, const std::string& filename, const std::string& phase_name); @@ -108,6 +115,7 @@ unique_ptr newKinetics(const std::vector& phases, * to the Kinetics object. * @param rootNode The root node of the file containing the phase definition, * which will be treated as the default source for reactions + * @ingroup kineticsmgr */ void addReactions(Kinetics& kin, const AnyMap& phaseNode, const AnyMap& rootNode=AnyMap()); diff --git a/include/cantera/kinetics/MultiRate.h b/include/cantera/kinetics/MultiRate.h index 1406a6e138b..e83b1f94c52 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 b132825b43f..b0039f4080d 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 a70eb4b0961..0efb2ab980e 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 1074c1cb652..2487e0845bb 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 82a65bdad9b..bf3a6ca96fa 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 8d6d370aeb0..076753d48f1 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 a8e716d06d3..68d6b27e0f8 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 88cb00ddcdc..9401a4cddaa 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 Coverage-Dependent 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,7 +52,6 @@ class Units; * @code * Rate* f = ReactionRateFactory::factory()->newReactionRate(type, c) * @endcode - * * @ingroup reactionGroup */ class ReactionRateFactory @@ -57,6 +82,7 @@ class ReactionRateFactory //! Create a new empty ReactionRate object /*! * @param type string identifying type of reaction rate. + * @ingroup reactionGroup */ shared_ptr newReactionRate(const std::string& type); @@ -65,6 +91,7 @@ shared_ptr newReactionRate(const std::string& type); * @param rate_node AnyMap node describing reaction rate. * @param rate_units Vector describing unit system of the reaction rate; each element * specifies Unit and exponent applied to the unit. + * @ingroup reactionGroup */ shared_ptr newReactionRate( const AnyMap& rate_node, const UnitStack& rate_units); @@ -72,6 +99,7 @@ shared_ptr newReactionRate( //! Create a new Rate object using the specified parameters /*! * @param rate_node AnyMap node describing reaction rate. + * @ingroup reactionGroup */ shared_ptr newReactionRate(const AnyMap& rate_node); diff --git a/include/cantera/kinetics/StoichManager.h b/include/cantera/kinetics/StoichManager.h index cc6b544c96b..63d3961626b 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 d404a85ef1b..fac1a6b8d16 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: