added comments and documentation

LLNL · Mar 8, 2024 · 5e3d249 · 5e3d249
1 parent 2975396
commit 5e3d249
Show file tree

Hide file tree

Showing 6 changed files with 129 additions and 59 deletions.
diff --git a/Source/ERF.H b/Source/ERF.H
@@ -375,6 +375,7 @@ private:
 
     void initialize_integrator (int lev, amrex::MultiFab& cons_mf, amrex::MultiFab& vel_mf);
 
+    // Initialize the microphysics object
     void initializeMicrophysics (const int&);
 
     // Compute a vector of new MultiFabs by copying from valid region and filling ghost cells

diff --git a/Source/ERF.cpp b/Source/ERF.cpp
@@ -918,8 +918,9 @@ ERF::InitData ()
     BL_PROFILE_VAR_STOP(InitData);
 }
 
+// Initialize microphysics object
 void
-ERF::initializeMicrophysics (const int& a_nlevsmax)
+ERF::initializeMicrophysics (const int& a_nlevsmax /*!< number of AMR levels */)
 {
     if (Microphysics::modelType(solverChoice.moisture_type) == MoistureModelType::Eulerian) {
 

diff --git a/Source/Microphysics/EulerianMicrophysics.H b/Source/Microphysics/EulerianMicrophysics.H
@@ -1,3 +1,7 @@
+/*! @file EulerianMicrophysics.H
+ *  \brief Containes the Eulerian microphysics class
+ */
+
 #ifndef EULERIANMICROPHYSICS_H
 #define EULERIANMICROPHYSICS_H
 
@@ -6,16 +10,20 @@
 #include "Kessler.H"
 #include "Microphysics.H"
 
+/*! \brief Eulerian microphysics interface */
 class EulerianMicrophysics : public Microphysics {
 
 public:
 
+    /*! \brief Null constructor */
     EulerianMicrophysics () { }
 
+    /*! \brief default destructor */
     ~EulerianMicrophysics () = default;
 
-    EulerianMicrophysics ( const int& nlev,
-                           const MoistureType& a_model_type )
+    /*! \brief Constructor: create the moisture model */
+    EulerianMicrophysics ( const int& nlev, /*!< Number of AMR levels */
+                           const MoistureType& a_model_type /*!< moisture model */)
     {
         AMREX_ASSERT( Microphysics::modelType(a_model_type) == MoistureModelType::Eulerian );
         m_moist_model.resize(nlev);
@@ -34,81 +42,84 @@ public:
         }
     }
 
-    void
-    Define (const int& lev,
-            SolverChoice& sc) override
+    /*! \brief Define the moisture model */
+    void Define (const int& lev, /*!< AMR level */
+                 SolverChoice& sc /*!< Solver choice object */) override
     {
         m_moist_model[lev]->Define(sc);
     }
 
-    void
-    Init (const int& lev,
-          const amrex::MultiFab& cons_in,
-          const amrex::BoxArray& grids,
-          const amrex::Geometry& geom,
-          const amrex::Real& dt_advance) override
+    /*! \brief Initialize the moisture model */
+    void Init ( const int& lev, /*!< AMR level */
+                const amrex::MultiFab& cons_in, /*!< Conserved state variables */
+                const amrex::BoxArray& grids,   /*!< Grids */
+                const amrex::Geometry& geom,    /*!< Geometry */
+                const amrex::Real& dt_advance   /*!< Time step */ ) override
     {
         m_moist_model[lev]->Init(cons_in, grids, geom, dt_advance);
     }
 
-    void
-    Advance (   const int& lev,
-                const amrex::Real& dt_advance,
-                const SolverChoice &solverChoice,
-                amrex::Vector<amrex::Vector<amrex::MultiFab>>&,
-                const amrex::Vector<std::unique_ptr<amrex::MultiFab>>& ) override
+    /*! \brief Advance the moisture model for one time step */
+    void Advance (  const int& lev, /*!< AMR level */
+                    const amrex::Real& dt_advance, /*!< Time step */
+                    const SolverChoice &solverChoice, /*!< Solver choice object */
+                    amrex::Vector<amrex::Vector<amrex::MultiFab>>&, /*!< Dycore state variables */
+                    const amrex::Vector<std::unique_ptr<amrex::MultiFab>>& /*!< terrain */) override
     {
         m_moist_model[lev]->Advance(dt_advance, solverChoice);
     }
 
-    void
-    Diagnose (const int& lev) override
+    /*! \brief compute diagnostics */
+    void Diagnose (const int& lev /*!< AMR level */) override
     {
         m_moist_model[lev]->Diagnose();
     }
 
-    void
-    Update_Micro_Vars_Lev (const int& lev, amrex::MultiFab& cons_in) override
+    /*! \brief update microphysics variables from ERF state variables */
+    void Update_Micro_Vars_Lev (const int& lev, /*! AMR level */
+                                amrex::MultiFab& cons_in /*!< Conserved state variables */) override
     {
         m_moist_model[lev]->Update_Micro_Vars(cons_in);
     }
 
-    void
-    Update_State_Vars_Lev (const int& lev, amrex::MultiFab& cons_in) override
+    /*! \brief update ERF state variables from microphysics variables */
+    void Update_State_Vars_Lev (const int& lev, /*!< AMR level */
+                                amrex::MultiFab& cons_in /*!< Conserved state variables */) override
     {
         m_moist_model[lev]->Update_State_Vars(cons_in);
     }
 
-    amrex::MultiFab*
-    Get_Qmoist_Ptr (const int& lev, const int& varIdx) override
+    /*! \brief get pointer to a moisture variable */
+    amrex::MultiFab* Get_Qmoist_Ptr (const int& lev, /*!< AMR level */
+                                     const int& varIdx /*!< moisture variable index */) override
     {
         return m_moist_model[lev]->Qmoist_Ptr(varIdx);
     }
 
-    int
-    Get_Qmoist_Size (const int& /* lev */) override
+    /*! \brief get the number of moisture model variables */
+    int Get_Qmoist_Size (const int& /* lev */) override
     {
         return m_moist_model[0]->Qmoist_Size();
     }
 
-    int
-    Get_Qstate_Size () override
+    /*! \brief get the number of moisture-model-related conserved state variables */
+    int Get_Qstate_Size () override
     {
         return m_moist_model[0]->Qstate_Size();
     }
 
 protected:
 
+    /*! \brief Create and set the specified moisture model */
     template<class NewMoistModel>
-    void
-    SetModel ()
+    void SetModel ()
     {
         for (int lev(0); lev<m_moist_model.size(); ++lev) {
             m_moist_model[lev] = std::make_unique<NewMoistModel>();
         }
     }
 
 private:
-    amrex::Vector<std::unique_ptr<NullMoist>> m_moist_model;
+    amrex::Vector<std::unique_ptr<NullMoist>> m_moist_model; /*!< moisture model */
 };
 #endif
diff --git a/Source/Microphysics/LagrangianMicrophysics.H b/Source/Microphysics/LagrangianMicrophysics.H
@@ -1,3 +1,7 @@
+/*! @file LagrangianMicrophysics.H
+ *  \brief Containes the Lagrangian microphysics class
+ */
+
 #ifndef LAGRANGIANMICROPHYSICS_H
 #define LAGRANGIANMICROPHYSICS_H
 
@@ -12,101 +16,125 @@
 /* forward declaration */
 class ERFPC;
 
+/*! \brief Eulerian microphysics interface
+ *
+ * One key difference from #EulerianMicrophysics is that only the base AMR
+ * level has the moisture model. Thus, for higher AMR levels, the microphysics
+ * interface need not do anything. The number of conserved state variables for
+ * moisture (RhoQ1, RhoQ2, ...) are the same for all AMR levels; however, for
+ * levels other than the base, they just contain and evolve zeros. */
 class LagrangianMicrophysics : public Microphysics {
 
 public:
 
+    /*! \brief Null constructor */
     LagrangianMicrophysics () { }
 
+    /*! \brief default destructor */
     ~LagrangianMicrophysics () = default;
 
-    LagrangianMicrophysics (  const int& /* nlev */,
-                              const MoistureType& a_model_type )
+    /*! \brief Constructor: create the moisture model */
+    LagrangianMicrophysics (  const int& /* nlev */, /*!< Number of AMR levels */
+                              const MoistureType& a_model_type /*!< moisture model */ )
     {
         AMREX_ASSERT( Microphysics::modelType(a_model_type) == MoistureModelType::Lagrangian );
         amrex::Abort("No Lagrangian moisture model implemented yet!") ;
     }
 
-    void Define (const int& lev,
-                 SolverChoice& sc) override
+    /*! \brief Define the moisture model */
+    void Define (const int& lev, /*!< AMR level */
+                 SolverChoice& sc /*!< Solver choice object */) override
     {
         if (lev > 0) return;
         m_moist_model->Define(sc);
     }
 
-    void Init (const int& lev,
-               const amrex::MultiFab& cons_in,
-               const amrex::BoxArray& grids,
-               const amrex::Geometry& geom,
-               const amrex::Real& dt_advance) override
+    /*! \brief Initialize the moisture model */
+    void Init ( const int& lev, /*!< AMR level */
+                const amrex::MultiFab& cons_in, /*!< Conserved state variables */
+                const amrex::BoxArray& grids,   /*!< Grids */
+                const amrex::Geometry& geom,    /*!< Geometry */
+                const amrex::Real& dt_advance   /*!< Time step */ ) override
     {
         if (lev > 0) return;
         m_moist_model->Init(cons_in, grids, geom, dt_advance);
     }
 
-    void Advance ( const int& lev,
-                   const amrex::Real& dt_advance,
-                   const SolverChoice&,
-                   amrex::Vector<amrex::Vector<amrex::MultiFab>>& a_vars,
-                   const amrex::Vector<std::unique_ptr<amrex::MultiFab>>& a_z) override
+    /*! \brief Advance the moisture model for one time step */
+    void Advance (  const int& lev, /*!< AMR level */
+                    const amrex::Real& dt_advance, /*!< Time step */
+                    const SolverChoice &solverChoice, /*!< Solver choice object */
+                    amrex::Vector<amrex::Vector<amrex::MultiFab>>&, /*!< Dycore state variables */
+                    const amrex::Vector<std::unique_ptr<amrex::MultiFab>>& /*!< terrain */) override
     {
         if (lev > 0) return;
         m_moist_model->Advance(dt_advance, a_vars, a_z);
     }
 
-    void Diagnose (const int& lev) override
+    /*! \brief compute diagnostics */
+    void Diagnose (const int& lev /*!< AMR level */) override
     {
         if (lev > 0) return;
         m_moist_model->Diagnose();
     }
 
-    void Update_Micro_Vars_Lev (const int& lev, amrex::MultiFab& cons_in) override
+    /*! \brief update microphysics variables from ERF state variables */
+    void Update_Micro_Vars_Lev (const int& lev, /*! AMR level */
+                                amrex::MultiFab& cons_in /*!< Conserved state variables */) override
     {
         if (lev > 0) return;
         m_moist_model->Update_Micro_Vars(cons_in);
     }
 
-    void Update_State_Vars_Lev (const int& lev, amrex::MultiFab& cons_in) override
+    /*! \brief update ERF state variables from microphysics variables */
+    void Update_State_Vars_Lev (const int& lev, /*!< AMR level */
+                                amrex::MultiFab& cons_in /*!< Conserved state variables */) override
     {
         if (lev > 0) return;
         m_moist_model->Update_State_Vars(cons_in);
     }
 
-    amrex::MultiFab* Get_Qmoist_Ptr (const int& lev, const int& varIdx) override
+    /*! \brief get pointer to a moisture variable */
+    amrex::MultiFab* Get_Qmoist_Ptr (const int& lev, /*!< AMR level */
+                                     const int& varIdx /*!< moisture variable index */) override
     {
         return (lev > 0 ? nullptr : m_moist_model->Qmoist_Ptr(varIdx));
     }
 
-    int Get_Qmoist_Size (const int& a_lev) override
+    /*! \brief get the number of moisture model variables */
+    int Get_Qmoist_Size (const int& a_lev /*!< AMR level */) override
     {
         return (a_lev > 0 ? 0 : m_moist_model->Qmoist_Size());
     }
 
+    /*! \brief get the number of moisture-model-related conserved state variables */
     int Get_Qstate_Size () override
     {
         return m_moist_model->Qstate_Size();
     }
 
+    /*! \brief get the particle container from the moisture model */
     inline ERFPC* getParticleContainer() const
     {
         return m_moist_model->getParticleContainer();
     }
 
+    /*! \brief get the name of the moisture model's particle container */
     inline const std::string& getName() const
     {
         return m_moist_model->getName();
     }
 
 protected:
 
+    /*! \brief Create and set the specified moisture model */
     template<class NewMoistModel>
-    void
-    SetModel ()
+    void SetModel ()
     {
         m_moist_model = std::make_unique<NewMoistModel>();
     }
 
-    std::unique_ptr<NullMoistLagrangian> m_moist_model;
+    std::unique_ptr<NullMoistLagrangian> m_moist_model; /*!< moisture model */
 };
 
 #endif

diff --git a/Source/Microphysics/Microphysics.H b/Source/Microphysics/Microphysics.H
@@ -1,42 +1,59 @@
+/*! @file Microphysics.H
+ *  \brief Containes the base class for microphysics
+ */
+
 #ifndef MICROPHYSICS_H
 #define MICROPHYSICS_H
 
 #include "DataStruct.H"
 
+/*! \brief Base class for microphysics interface */
 class Microphysics {
 
 public:
 
+    /*! \brief Null constructor */
     Microphysics () { }
 
+    /*! \brief default destructor */
     virtual ~Microphysics () = default;
 
+    /*! \brief define the microphysics object */
     virtual void Define (const int&, SolverChoice&) = 0;
 
+    /*! \brief initialize the microphysics object */
     virtual void Init (const int&,
                        const amrex::MultiFab&,
                        const amrex::BoxArray&,
                        const amrex::Geometry&,
                        const amrex::Real&) = 0;
 
+    /*! \brief advance microphysics for one time step */
     virtual void Advance (  const int&,
                             const amrex::Real&,
                             const SolverChoice&,
                             amrex::Vector<amrex::Vector<amrex::MultiFab>>&,
                             const amrex::Vector<std::unique_ptr<amrex::MultiFab>>& ) = 0;
 
+    /*! \brief compute diagnostics */
     virtual void Diagnose (const int&) = 0;
 
+    /*! \brief update microphysics variables from ERF state variables */
     virtual void Update_Micro_Vars_Lev (const int&, amrex::MultiFab&) = 0;
 
+    /*! \brief update ERF state variables from microphysics variables */
     virtual void Update_State_Vars_Lev (const int&, amrex::MultiFab&) = 0;
 
+    /*! \brief get pointer to a moisture variable */
     virtual amrex::MultiFab* Get_Qmoist_Ptr (const int&, const int&) = 0;
 
+    /*! \brief get the number of moisture model variables */
     virtual int Get_Qmoist_Size (const int&) = 0;
 
+    /*! \brief get the number of moisture-model-related conserved state variables */
     virtual int Get_Qstate_Size () = 0;
 
+    /*! \brief query if a specified moisture model is Eulerian or Lagrangian */
     static MoistureModelType modelType(const MoistureType a_moisture_type)
     {
         if (    (a_moisture_type == MoistureType::SAM)