Document member variables of IdasIntegrator and FlowReactor

include/cantera/numerics/IdasIntegrator.h

@@ -18,7 +18,7 @@ namespace Cantera
 {
 
 /**
- * Wrapper for Sundials IDA solver
+ * Wrapper for Sundials IDAS solver
  * @see FuncEval.h. Classes that use IdasIntegrator:
  * FlowReactor
  */
@@ -82,34 +82,50 @@ class IdasIntegrator : public Integrator
     //! containing the method name and the error code stashed by the ida_err() function.
     void checkError(long flag, const string& ctMethod, const string& idaMethod) const;
 
-    size_t m_neq;
+    size_t m_neq; //!< Number of equations/variables in the system
     void* m_ida_mem = nullptr; //!< Pointer to the IDA memory for the problem
     void* m_linsol = nullptr; //!< Sundials linear solver object
     void* m_linsol_matrix = nullptr; //!< matrix used by Sundials
     SundialsContext m_sundials_ctx; //!< SUNContext object for Sundials>=6.0
+
+    //! Object implementing the DAE residual function \f$ f(t, y, \dot{y}) = 0\f$
     FuncEval* m_func = nullptr;
-    double m_t0 = 0.0;
+
+    double m_t0 = 0.0; //!< The start time for the integrator
     double m_time; //!< The current integrator time
-    N_Vector m_y = nullptr;
-    N_Vector m_ydot = nullptr;
-    N_Vector m_abstol = nullptr;
-    string m_type = "DENSE";
+    N_Vector m_y = nullptr; //!< The current system state
+    N_Vector m_ydot = nullptr; //!< The time derivatives of the system state
+    N_Vector m_abstol = nullptr; //!< Absolute tolerances for each state variable
+    string m_type = "DENSE"; //!< The linear solver type. @see setLinearSolverType()
+
+    //! Flag indicating whether scalar (`IDA_SS`) or vector (`IDA_SV`) absolute
+    //! tolerances are being used.
     int m_itol;
-    int m_maxord = 0;
-    double m_reltol = 1.0e-9;
-    double m_abstols = 1.0e-15;
-    double m_reltolsens, m_abstolsens;
+
+    int m_maxord = 0; //!< Maximum order allowed for the BDF method
+    double m_reltol = 1.0e-9; //!< Relative tolerance for all state variables
+    double m_abstols = 1.0e-15; //!< Scalar absolute tolerance
+    double m_reltolsens; //!< Scalar relative tolerance for sensitivities
+    double m_abstolsens; //!< Scalar absolute tolerance for sensitivities
+
+    //!! Number of variables for which absolute tolerances were provided
     size_t m_nabs = 0;
-    double m_hmax = 0.0;
+
+    double m_hmax = 0.0; //!< Maximum time step size. Zero means infinity.
+
+    //! Maximum number of internal steps taken in a call to integrate()
     int m_maxsteps = 20000;
+
+    //! Maximum number of error test failures in attempting one step
     int m_maxErrTestFails = -1;
-    N_Vector* m_yS = nullptr;
-    N_Vector* m_ySdot = nullptr;
-    size_t m_np;
-    N_Vector m_constraints = nullptr;
 
-    //! Indicates whether the sensitivities stored in m_yS have been updated
-    //! for at the current integrator time.
+    size_t m_np; //!< Number of sensitivity parameters
+    N_Vector* m_yS = nullptr; //!< Sensitivities of y, size #m_np by #m_neq.
+    N_Vector* m_ySdot = nullptr; //!< Sensitivities of ydot, size #m_np by #m_neq.
+    N_Vector m_constraints = nullptr; //!<
+
+    //! Indicates whether the sensitivities stored in #m_yS and #m_ySdot have been
+    //! updated for the current integrator time.
     bool m_sens_ok;
 
     //! Maximum number of nonlinear solver iterations at one solution
@@ -124,7 +140,7 @@ class IdasIntegrator : public Integrator
     //! If true, the algebraic variables don't contribute to error tolerances
     bool m_setSuppressAlg = false;
 
-    //! Initial IDA stepsize
+    //! Initial IDA step size
     double m_init_step = 1e-14;
 };
 

include/cantera/zeroD/FlowReactor.h

@@ -11,11 +11,10 @@
 namespace Cantera
 {
 
-//! Adiabatic flow in a constant-area duct.
+//! Adiabatic flow in a constant-area duct with homogeneous and heterogeneous reactions
 class FlowReactor : public IdealGasReactor
 {
 public:
-    //! Note: currently assumes a cylinder
     FlowReactor() = default;
 
     string type() const override {
@@ -26,6 +25,7 @@ class FlowReactor : public IdealGasReactor
         return false;
     }
 
+    //! Not implemented; FlowReactor implements getStateDAE() instead.
     void getState(double* y) override {
         throw NotImplementedError("FlowReactor::getState");
     }
@@ -35,17 +35,13 @@ class FlowReactor : public IdealGasReactor
     void syncState() override;
     void updateState(double* y) override;
 
-    /*!
-     * Not implemented for FlowReactor
-     */
+    //! Not implemented; FlowReactor implements evalDae() instead.
     void eval(double t, double* LHS, double* RHS) override {
         throw NotImplementedError("FlowReactor::eval");
     }
 
     void evalDae(double t, double* y, double* ydot, double* residual) override;
 
-    //! Given a vector of length neq(), mark which variables should be
-    //! considered algebraic constraints
     void getConstraints(double* constraints) override;
 
     //! Set the mass flow rate through the reactor [kg/s]
@@ -109,10 +105,14 @@ class FlowReactor : public IdealGasReactor
     void updateSurfaceState(double* y) override;
 
 protected:
+    //! Density [kg/m^3]. First component of the state vector.
+    double m_rho = NAN;
+    //! Axial velocity [m/s]. Second component of the state vector.
     double m_u = NAN;
-    double m_T = NAN;
+    //! Pressure [Pa]. Third component of the state vector.
     double m_P = NAN;
-    double m_rho = NAN;
+    //! Temperature [K]. Fourth component of the state vector.
+    double m_T = NAN;
     //! offset to the species equations
     const size_t m_offset_Y = 4;
     //! reactor area [m^2]
@@ -123,7 +123,6 @@ class FlowReactor : public IdealGasReactor
     vector_fp m_sdot_temp;
     //! temporary storage for species partial molar enthalpies
     vector_fp m_hk;
-
     //! steady-state relative tolerance, used to determine initial surface coverages
     double m_ss_rtol = 1e-7;
     //! steady-state absolute tolerance, used to determine initial surface coverages