Document LoadVector

Author: Q-Minh

source/pbat/fem/Gradient.h

@@ -49,6 +49,8 @@ namespace fem {
  * \f]
  *
  * where \f$ g \f$ is the number of evaluation points.
+ * 
+ * @note Link to my higher-level FEM crash course doc.
  *
  * @tparam TMesh
  */

source/pbat/fem/LaplacianMatrix.h

@@ -30,7 +30,7 @@ namespace fem {
  * The precise definition of the Laplacian matrix's symmetric part is given by
  * \f$ \mathbf{L}_{ij} = \int_\Omega -\nabla \phi_i \cdot \nabla \phi_j d\Omega \f$.
  *
- * * @todo Explain the Laplacian matrix and its construction and link to my higher-level FEM crash
+ * @todo Explain the Laplacian matrix and its construction and link to my higher-level FEM crash
  * course doc.
  *
  * This matrix-free Laplacian requires the following inputs:

source/pbat/fem/LoadVector.h

@@ -1,3 +1,13 @@
+/**
+ * @file LoadVector.h
+ * @author Quoc-Minh Ton-That ([email protected])
+ * @brief LoadVector API and implementation.
+ * @date 2025-02-11
+ *
+ * @copyright Copyright (c) 2025
+ *
+ */
+
 #ifndef PBAT_FEM_LOAD_VECTOR_H
 #define PBAT_FEM_LOAD_VECTOR_H
 
@@ -14,24 +24,38 @@
 namespace pbat {
 namespace fem {
 
+/**
+ * @brief A matrix-free representation of a finite element load vector \f$ \mathbf{f}_i =
+ * \int_\Omega \mathbf{f}(X) \phi_i(X) \f$ under Galerkin projection.
+ *
+ * \note Assumes \f$ \mathbf{f}(X) \f$ is piecewise constant over the elements.
+ *
+ * \todo Link to my higher-level FEM crash course doc.
+ *
+ * @tparam TMesh Type satisfying concept CMesh
+ * @tparam QuadratureOrder Quadrature order for integrating the load vector
+ */
 template <CMesh TMesh, int QuadratureOrder>
 struct LoadVector
 {
   public:
-    using SelfType              = LoadVector<TMesh, QuadratureOrder>;
-    using MeshType              = TMesh;
-    using ElementType           = typename TMesh::ElementType;
-    using QuadratureRuleType    = typename ElementType::template QuadratureType<QuadratureOrder>;
-    static int constexpr kOrder = ElementType::kOrder;
-    static int constexpr kQuadratureOrder = QuadratureOrder;
+    using SelfType    = LoadVector<TMesh, QuadratureOrder>; ///< Self type
+    using MeshType    = TMesh;                              ///< Mesh type
+    using ElementType = typename TMesh::ElementType;        ///< Element type
+    using QuadratureRuleType =
+        typename ElementType::template QuadratureType<QuadratureOrder>; ///< Quadrature rule type
+    static int constexpr kOrder = ElementType::kOrder; ///< Polynomial order of the load vector
+    static int constexpr kQuadratureOrder = QuadratureOrder; ///< Quadrature order
 
     /**
-     * @brief
-     * @tparam TDerived
-     * @param mesh
-     * @param detJe |#quad.pts.|x|#elements| affine element jacobian determinants at quadrature
+     * @brief Construct a new LoadVector object
+     * @tparam TDerived Eigen dense expression type
+     * @param mesh Finite element mesh
+     * @param detJe `|# quad.pts.|x|# elements|` affine element jacobian determinants at quadrature
      * points
-     * @param fe |dims|x|#elements| piecewise element constant load, or |dims|x1 constant load
+     * @param fe `|dims|x|# elements|` piecewise element constant load, or `|dims|x1` constant load
+     * @param dims Dimensionality of image of FEM function space
+     * @pre `dims >= 1` and `fe.cols() == 1 || fe.cols() == mesh.E.cols()` and `fe.rows() == dims`
      */
     template <class TDerived>
     LoadVector(
@@ -43,29 +67,33 @@ struct LoadVector
     SelfType& operator=(SelfType const&) = delete;
 
     /**
-     * @brief Transforms this matrix-free mass matrix representation into sparse compressed format.
-     * @return
+     * @brief Transforms this element-wise load vector representation into a global load vector.
+     * @return VectorX Global load vector
      */
     VectorX ToVector() const;
 
     /**
-     * @brief
-     * @tparam TDerived
-     * @param fe |dims|x|#elements| piecewise element constant load, or |dims|x1 constant load
+     * @brief Set the external loading
+     * @tparam TDerived Eigen dense expression type
+     * @param fe `|dims|x|# elements|` piecewise element constant load, or `|dims|x1` constant load
      */
     template <class TDerived>
     void SetLoad(Eigen::DenseBase<TDerived> const& fe);
 
+    /**
+     * @brief Check if the state of this load vector is valid
+     */
     void CheckValidState() const;
 
     MeshType const& mesh; ///< The finite element mesh
-    MatrixX fe;           ///< |dims|x|#elements| piecewise element constant load
-    MatrixX N; ///< |ElementType::kNodes|x|#elements| integrated element shape functions. To
-               ///< obtain the element force vectors, compute Neint \kron I_{dims} * f
-    Eigen::Ref<MatrixX const> detJe; ///< |# element quadrature points|x|#elements| matrix of
+    MatrixX fe;           ///< `|dims|x|# elements|` piecewise element constant load
+    MatrixX N; ///< `|ElementType::kNodes|x|# elements|` integrated element shape functions. See
+               ///< (IntegratedShapeFunctions()).
+    Eigen::Ref<MatrixX const> detJe; ///< `|# element quadrature points|x|# elements|` matrix of
                                      ///< jacobian determinants at element quadrature points
     int dims; ///< Dimensionality of image of FEM function space, i.e. this load vector is
-              ///< actually f \kronecker 1_{dims \times dims}. Should be >= 1.
+              ///< actually \f$ \mathbf{f} \kronecker 1_{dims \times dims} \f$. Should have `dims >=
+              ///< 1`.
 };
 
 template <CMesh TMesh, int QuadratureOrder>