Documentation mobility model, cahn-hilliard filtering (#1016)

Description of the problem Documentation for the mobility models and phase filtering for Cahn-Hilliard equations
chaos-polymtl · Feb 9, 2024 · ad73849 · ad73849
1 parent 23dbe56
commit ad73849
Show file tree

Hide file tree

Showing 2 changed files with 103 additions and 69 deletions.
diff --git a/include/core/mobility_cahn_hilliard_model.h b/include/core/mobility_cahn_hilliard_model.h
@@ -20,57 +20,66 @@
 #include <core/interface_property_model.h>
 
 /**
- * @brief Abstract class that allows to calculate the
- * mobility for the Cahn-Hilliard-Navier-Stokes equations.
+ * @brief Implementation of the computation of the mobility
+ * for Cahn-Hilliard equations.
  */
 class MobilityCahnHilliardModel : public InterfacePropertyModel
 {
 public:
   /**
-   * @brief Instantiates and returns a pointer to a MobilityCahnHilliardModel object by casting it to
-   * the proper child class
+   * @brief Instantiate and return a pointer to a MobilityCahnHilliardModel
+   * object by casting it to the proper child class.
    *
-   * @param material_interaction_parameters Parameters for the mobility calculation
+   * @param[in] material_interaction_parameters Parameters for the mobility
+   * calculation.
    */
   static std::shared_ptr<MobilityCahnHilliardModel>
   model_cast(
     const Parameters::MaterialInteractions &material_interaction_parameters);
 
   /**
-   * @brief Pure virtual method to access the mobility constant
-   * @return value of the mobility constant
+   * @brief Pure virtual method to access the mobility constant.
+   * @return Value of the mobility constant.
    */
   virtual double
   get_mobility_constant() = 0;
 
   /**
-   * @brief Definition of a virtual destructor
+   * @brief Definition of a virtual destructor for the class.
    */
   virtual ~MobilityCahnHilliardModel() = default;
 };
 
 /**
- * @brief Constant mobility_cahn_hilliard_constant.
+ * @brief Constant mobility model.
+ *
+ * The mobility function is the following : \f$M(\phi) = D \f$ where D is the
+ * mobility constant.
  */
 class MobilityCahnHilliardModelConstant : public MobilityCahnHilliardModel
 {
 public:
   /**
    * @brief Default constructor
+   *
+   * @param[in] p_mobility_cahn_hilliard_constant the user defined mobility
+   * constant.
    */
   MobilityCahnHilliardModelConstant(
     const double p_mobility_cahn_hilliard_constant)
     : mobility_cahn_hilliard_constant(p_mobility_cahn_hilliard_constant)
   {}
 
   /**
-   * @brief Destructor of derived class
+   * @brief Destructor of derived class.
    */
   ~MobilityCahnHilliardModelConstant() = default;
 
   /**
-   * @brief Method to access the mobility constant, though it returns the same value as the value function, it is implemented here for generality.
-   * @return value of the mobility constant
+   * @brief Return the mobility constant, though it returns the same
+   * value as the value method, it is implemented here for generality.
+   *
+   * @return Value of the mobility constant.
    */
   double
   get_mobility_constant() override
@@ -79,9 +88,10 @@ class MobilityCahnHilliardModelConstant : public MobilityCahnHilliardModel
   }
 
   /**
-   * @brief value Computes mobility_cahn_hilliard.
-   * @param fields_value Value of the various field on which the property may depend.
-   * @return value of the physical property calculated with the fields_value
+   * @brief Compute the mobility.
+   * @param[in] fields_value Value of the various field on which the mobility
+   * may depend.
+   * @return Value of the mobility.
    */
   double
   value(const std::map<field, double> & /*fields_value*/) override
@@ -90,9 +100,10 @@ class MobilityCahnHilliardModelConstant : public MobilityCahnHilliardModel
   }
 
   /**
-   * @brief vector_value Calculates the vector of mobility_cahn_hilliard.
-   * @param field_vectors Vectors of the fields on which the mobility_cahn_hilliard may depend.
-   * @param property_vector Vectors of the mobility_cahn_hilliard values
+   * @brief Calculate the vector of mobility_cahn_hilliard.
+   * @param[in] field_vectors Vectors of the fields on which the mobility
+   * may depend.
+   * @param[out] property_vector Vectors of the mobility values
    */
   void
   vector_value(const std::map<field, std::vector<double>> & /*field_vectors*/,
@@ -104,13 +115,15 @@ class MobilityCahnHilliardModelConstant : public MobilityCahnHilliardModel
   }
 
   /**
-   * @brief jacobian Calculates the jacobian (the partial derivative) of the density with respect to a field
-   * @param field_values Value of the various fields on which the property may depend.
-   * @param id Indicator of the field with respect to which the jacobian
+   * @brief Calculate the jacobian (the partial derivative) of the
+   * mobility with respect to a field.
+   * @param[in] field_values Value of the various fields on which the mobility
+   * may depend.
+   * @param[in] id Indicator of the field with respect to which the jacobian
    * should be calculated.
-   * @return value of the partial derivative of the density with respect to the field.
+   * @return Value of the partial derivative of the mobility with respect to
+   * the field.
    */
-
   double
   jacobian(const std::map<field, double> & /*field_values*/,
            field /*id*/) override
@@ -119,12 +132,14 @@ class MobilityCahnHilliardModelConstant : public MobilityCahnHilliardModel
   }
 
   /**
-   * @brief vector_jacobian Calculates the derivative of the density with respect to a field.
-   * @param field_vectors Vector for the values of the fields used to evaluate the property.
-   * @param id Identifier of the field with respect to which a derivative should be calculated.
-   * @param jacobian vector of the value of the derivative of the density with respect to the field id.
+   * @brief Calculate the derivative of the mobility with respect to a field.
+   * @param[in] field_vectors Vector for the values of the fields used to
+   * evaluate the mobility.
+   * @param[in] id Identifier of the field with respect to which a derivative
+   * should be calculated.
+   * @param[out] jacobian_vector Vector of the value of the derivative of the
+   * mobility with respect to the field id.
    */
-
   void
   vector_jacobian(
     const std::map<field, std::vector<double>> & /*field_vectors*/,
@@ -139,13 +154,19 @@ class MobilityCahnHilliardModelConstant : public MobilityCahnHilliardModel
 };
 
 /**
- * @brief Quartic mobility_cahn_hilliard.
+ * @brief Quartic mobility model.
+ *
+ * The mobility function is the following : \f$M(\phi) = D(1-\phi^2)^2 \f$
+ * where D is the mobility constant.
  */
 class MobilityCahnHilliardModelQuartic : public MobilityCahnHilliardModel
 {
 public:
   /**
-   * @brief Default constructor
+   * @brief Default constructor.
+   *
+   * @param[in] p_mobility_cahn_hilliard_constant the user defined mobility
+   * constant.
    */
   MobilityCahnHilliardModelQuartic(
     const double p_mobility_cahn_hilliard_constant)
@@ -155,13 +176,13 @@ class MobilityCahnHilliardModelQuartic : public MobilityCahnHilliardModel
   }
 
   /**
-   * @brief Destructor of derived class
+   * @brief Destructor of derived class.
    */
   ~MobilityCahnHilliardModelQuartic() = default;
 
   /**
-   * @brief Method to access the mobility constant, though it returns the same value as the value function, it is implemented here for generality
-   * @return value of the mobility constant
+   * @brief Return the mobility constant.
+   * @return Value of the mobility constant.
    */
   double
   get_mobility_constant() override
@@ -170,9 +191,10 @@ class MobilityCahnHilliardModelQuartic : public MobilityCahnHilliardModel
   }
 
   /**
-   * @brief value Calculates the mobility_cahn_hilliard.
-   * @param fields_value Value of the various field on which the property may depend.
-   * @return value of the physical property calculated with the fields_value.
+   * @brief Calculate the mobility.
+   * @param[in] fields_value Value of the various fields on which the mobility
+   * may depend.
+   * @return Value of the mobility calculated with the fields_value.
    */
   double
   value(const std::map<field, double> &fields_value) override
@@ -190,9 +212,10 @@ class MobilityCahnHilliardModelQuartic : public MobilityCahnHilliardModel
   }
 
   /**
-   * @brief vector_value Calculates the vector of mobility_cahn_hilliard_constant.
-   * @param field_vectors Vectors of the fields on which the mobility_cahn_hilliard_constant may depend.
-   * @param property_vector Vectors of the mobility_cahn_hilliard_constant values
+   * @brief Calculate the vector of mobility.
+   * @param[in] field_vectors Vectors of the fields on which the mobility
+   * may depend.
+   * @param[out] property_vector Vector of the mobility values.
    */
   void
   vector_value(const std::map<field, std::vector<double>> &field_vectors,
@@ -212,11 +235,14 @@ class MobilityCahnHilliardModelQuartic : public MobilityCahnHilliardModel
   }
 
   /**
-   * @brief jacobian Calculates the jacobian (the partial derivative) of the density with respect to a field
-   * @param field_values Value of the various fields on which the property may depend.
-   * @param id Indicator of the field with respect to which the jacobian
+   * @brief Calculate the jacobian (the partial derivative) of the
+   * mobility with respect to a field.
+   * @param[in] field_values Value of the various fields on which the mobility
+   * may depend.
+   * @param[in] id Indicator of the field with respect to which the Jacobian
    * should be calculated.
-   * @return value of the partial derivative of the density with respect to the field.
+   * @return Value of the partial derivative of the mobility with respect to
+   * the field.
    */
 
   double
@@ -235,10 +261,13 @@ class MobilityCahnHilliardModelQuartic : public MobilityCahnHilliardModel
   }
 
   /**
-   * @brief vector_jacobian Calculates the derivative of the density with respect to a field.
-   * @param field_vectors Vector for the values of the fields used to evaluate the property.
-   * @param id Identifier of the field with respect to which a derivative should be calculated.
-   * @param jacobian vector of the value of the derivative of the density with respect to the field id.
+   * @brief Calculate the derivative of the mobility with respect to a field.
+   * @param[in] field_vectors Vector for the values of the fields used to
+   * evaluate the mobility.
+   * @param[in] id Identifier of the field with respect to which a derivative
+   * should be calculated.
+   * @param[out] jacobian_vector Vector of the values of the derivatives of the
+   * mobility with respect to the field id.
    */
 
   void

diff --git a/include/solvers/cahn_hilliard_filter.h b/include/solvers/cahn_hilliard_filter.h
@@ -21,7 +21,7 @@
 #include <core/parameters_multiphysics.h>
 
 /**
- * @brief Filters phase fraction according to the selected filtering method
+ * @brief Filter phase fraction according to the selected filtering method.
  */
 class CahnHilliardFilterBase
 {
@@ -30,26 +30,27 @@ class CahnHilliardFilterBase
   {}
 
   /**
-   * @brief Instantiates and returns a pointer to a CahnHilliardFilterBase
-   * object by casting it to the proper child class
+   * @brief Instantiate and return a pointer to a CahnHilliardFilterBase
+   * object by casting it to the proper child class.
    *
-   * @param cahn_hilliard_parameters CahnHilliard model parameters
+   * @param[in] cahn_hilliard_parameters CahnHilliard model parameters.
    */
   static std::shared_ptr<CahnHilliardFilterBase>
   model_cast(const Parameters::CahnHilliard &cahn_hilliard_parameters);
 
   /**
-   * @brief Calculates the value of the filtered phase fraction
-   * @param unfiltered_phase Value of the phase fraction before applying the
-   * filter
-   * @return Value of the phase fraction after applying the filter
+   * @brief Calculate the value of the filtered phase fraction.
+   * @param[in] unfiltered_phase Value of the phase fraction before applying
+   * the filter.
+   * @return Value of the phase fraction after applying the filter.
    */
   virtual double
   filter_phase(const double &unfiltered_phase) = 0;
 };
 
 /**
- * @brief Used as a default when no filter is applied to the phase fraction
+ * @brief Used as a default when no filter is applied to the phase fraction.
+ *
  */
 class CahnHilliardNoFilter : public CahnHilliardFilterBase
 {
@@ -58,7 +59,7 @@ class CahnHilliardNoFilter : public CahnHilliardFilterBase
   {}
 
   /**
-   * @brief Returns the phase fraction with no modification
+   * @brief Return the phase fraction with no modification.
    */
   virtual double
   filter_phase(const double &unfiltered_phase) override
@@ -68,7 +69,7 @@ class CahnHilliardNoFilter : public CahnHilliardFilterBase
 };
 
 /**
- * @brief Calculates a filtered phase fraction for Cahn-Hilliard simulations.
+ * @brief Calculate a filtered phase fraction for Cahn-Hilliard simulations.
  * In this case, a simple clamping is performed on the phase fraction parameter
  * for it to remain in the [-1,1] interval.
  */
@@ -79,10 +80,10 @@ class CahnHilliardClipFilter : public CahnHilliardFilterBase
   {}
 
   /**
-   * @brief Calculates the value of the filtered phase fraction
-   * @param unfiltered_phase Value of the phase fraction before applying the
-   * filter
-   * @return Value of the phase fraction after applying the filter
+   * @brief Calculate the value of the filtered phase fraction.
+   * @param[in] unfiltered_phase Value of the phase fraction before applying the
+   * filter.
+   * @return Value of the phase fraction after applying the filter.
    */
   virtual double
   filter_phase(const double &unfiltered_phase) override
@@ -93,8 +94,10 @@ class CahnHilliardClipFilter : public CahnHilliardFilterBase
 };
 
 /**
- * @brief Calculates a filtered phase fraction for Cahn-Hilliard simulations.
- * The filtered phase is defined as \f$\phi_f = \tanh(\beta \phi)\f$.
+ * @brief Calculate a filtered phase fraction for Cahn-Hilliard simulations.
+ *
+ * The filtered phase is defined as \f$\phi_f = \tanh(\beta \phi)\f$ with
+ * \f$ \phi \f$ the unfiltered phase field.
  */
 class CahnHilliardTanhFilter : public CahnHilliardFilterBase
 {
@@ -104,10 +107,10 @@ class CahnHilliardTanhFilter : public CahnHilliardFilterBase
   {}
 
   /**
-   * @brief Calculates the value of the filtered phase fraction
-   * @param unfiltered_phase Value of the phase fraction before applying the
-   * filter
-   * @return Value of the phase fraction after applying the filter
+   * @brief Calculate the value of the filtered phase fraction.
+   * @param[in] unfiltered_phase Value of the phase fraction before applying the
+   * filter.
+   * @return Value of the phase fraction after applying the filter.
    */
   virtual double
   filter_phase(const double &unfiltered_phase) override
@@ -116,7 +119,9 @@ class CahnHilliardTanhFilter : public CahnHilliardFilterBase
   }
 
 private:
-  // User-defined parameter that influences how sharp the filtering is.
+  /**
+   * User-defined parameter that influences how sharp the filtering is.
+   */
   const double beta;
 };