Comments in include/dem/

applications/lethe-particles/dem.cc

@@ -32,7 +32,8 @@ main(int argc, char *argv[])
           // Parsing of the file
           prm.parse_input(argv[1]);
           dem_parameters.parse(prm);
-          const DEM::SolverType solver_type = dem_parameters.model_parameters.solver_type;
+          const DEM::SolverType solver_type =
+            dem_parameters.model_parameters.solver_type;
 
           if (solver_type == DEM::SolverType::dem)
             {
@@ -41,7 +42,13 @@ main(int argc, char *argv[])
             }
           else
             {
-              return 1;
+              AssertThrow(
+                false,
+                dealii::ExcMessage(
+                  "While reading the solver type from the input file, "
+                  "Lethe found a value different than \"dem\". As of January 2025, "
+                  "the lethe-particles application requires the uses of  "
+                  "\"solver type = dem\", which is the default value."));
             }
         }
 
@@ -54,16 +61,23 @@ main(int argc, char *argv[])
           // Parsing of the file
           prm.parse_input(argv[1]);
           dem_parameters.parse(prm);
-          const DEM::SolverType solver_type = dem_parameters.model_parameters.solver_type;
-
+          // const DEM::SolverType solver_type =
+          // dem_parameters.model_parameters.solver_type;
+          const DEM::SolverType solver_type = DEM::SolverType::dem;
           if (solver_type == DEM::SolverType::dem)
             {
               DEMSolver<3, DEM::SolverType::dem> problem(dem_parameters);
               problem.solve();
             }
           else
             {
-              return 1;
+              AssertThrow(
+                false,
+                dealii::ExcMessage(
+                  "While reading the solver type from the input file, "
+                  "Lethe found a value different than \"dem\". As of January 2025, "
+                  "the lethe-particles application requires the uses of  "
+                  "\"solver type = dem\", which is the default value."));
             }
         }
 

include/core/dem_properties.h

@@ -9,11 +9,12 @@
 
 namespace DEM
 {
-  /* The SolverType enum identifies which type of solver is using the DEM particles.
-   * This is used to identify which index corresponds to which properties. Two type of
-   * solvers are currently supported. DEM implies pure DEM simulation whereas cfd_dem
-   * is used to indicate simulations in which the particles are coupled to CFD. In the latter case
-   * the particles carry additional properties related to the particle-fluid coupling.
+  /* The SolverType enum identifies which type of solver is used by the DEM
+   * particles. This is used to identify which index corresponds to which
+   * properties. Two type of solvers are currently supported. DEM implies pure
+   * DEM simulation whereas cfd_dem is used to indicate simulations in which the
+   * particles are coupled to CFD. In the latter case the particles carry
+   * additional properties related to the particle-fluid coupling.
    */
   enum SolverType
   {
@@ -42,7 +43,7 @@ namespace DEM
       mass         = 8,
       n_properties = 9,
 
-    };
+    }
   };
 
   // Specialization for `cfd_dem`
@@ -67,7 +68,7 @@ namespace DEM
       mass                    = 14,
       volumetric_contribution = 15,
       n_properties            = 16,
-    };
+    }
   };
 
   /// Template specialization to select the adequate PropertiesIndex
@@ -86,18 +87,33 @@ namespace DEM
     using Index = CFDDEMsolver::PropertiesIndexCFDDEM;
   };
 
+  // This typename helps for code readability
   template <SolverType solver_type>
   using PropertiesIndex = typename PropertiesIndexEnum<solver_type>::Index;
 
-
+  /**
+   * @brief Return the number of properties stored on each particle.
+   * @tparam solve_type Type of solver used for the DEM.
+   * @return Number of DEM properties.
+   */
   template <SolverType solve_type>
   unsigned int
   get_number_properties();
 
+  /**
+   * @brief Controls the name of output variables for the vtu.
+   * @tparam dim An integer that denotes the number of spatial dimensions.
+   * @tparam solve_type Type of solver used for the DEM.
+   */
   template <int dim, SolverType solver_type>
   class DEMProperties
   {
   public:
+    /**
+     * @brief Return the names of each DEM property. Used to properly generate
+     * output files.
+     * @return A vector with the names of each property.
+     */
     static std::vector<std::pair<std::string, int>>
     get_properties_name();
   };

include/core/lethe_grid_tools.h

@@ -272,16 +272,19 @@ namespace LetheGridTools
    * Variables name are taken straight from this reference to ensure a better
    * readability.
    *
-   * @return A tuple in which 0. a vector of bools to determine if the particle is
-   * close to the triangle plane, 1. a vector of projected location of particles
-   * on the triangle, 2. a vector of normal vectors of the triangles
+   * @tparam dim An integer that denotes the number of spatial dimensions.
+   * @tparam solve_type Type of solver used for the DEM.
    *
    * @param triangle A vector of points that defines a triangle
    * @param particles A particle_iterator_range that refers to all the particles
    * located in the background (base) cell
    * @param n_particles_in_base_cell Number of particles in the base cell
    *
+   * * @return A tuple in which 0. a vector of bools to determine if the particle is
+   * close to the triangle plane, 1. a vector of projected location of particles
+   * on the triangle, 2. a vector of normal vectors of the triangles
    */
+
   template <int dim, DEM::SolverType solverType>
   std::
     tuple<std::vector<bool>, std::vector<Point<3>>, std::vector<Tensor<1, 3>>>

include/dem/adaptive_sparse_contacts.h

@@ -98,7 +98,8 @@ template class LinearAlgebra::distributed::Vector<int>;
  * flagged as active cells. It works with the assignment and verification of the
  * mobility status at nodes to check the status of the neighboring cells.
  *
- * @tparam dim Spatial dimension
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  */
 template <int dim, DEM::SolverType solver_type>
 class AdaptiveSparseContacts

include/dem/dem.h

@@ -47,6 +47,8 @@ using namespace DEM;
 /**
  * @brief Solver using the soft-sphere model of the discrete element method
  * (DEM) to simulate granular systems.
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  */
 template <int dim, DEM::SolverType solver_type>
 class DEMSolver
@@ -269,6 +271,8 @@ class DEMSolver
 
   /**
    * @brief The properties of the DEM simulation.
+   * @tparam dim An integer that denotes the number of spatial dimensions.
+   * @tparam solve_type Type of solver used for the DEM.
    */
   DEM::DEMProperties<dim, solver_type> properties_class;
 

include/dem/dem_contact_manager.h

@@ -29,6 +29,9 @@ using namespace DEM;
  *
  * This class mostly calls proper functions in regards the type of contacts for
  * the contact detection and updates of data containers.
+ *
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  */
 template <int dim, DEM::SolverType solver_type>
 class DEMContactManager

include/dem/dem_post_processing.h

@@ -32,7 +32,8 @@ namespace DEM
    * - Translational velocity
    * - Rotational (angular) velocity
    *
-   * @tparam dim Dimensionality of the problem (2D or 3D)
+   * @tparam dim An integer that denotes the number of spatial dimensions.
+   * @tparam solve_type Type of solver used for the DEM.
    * @tparam dem_statistics_variable Enum variable used to identify which
    * granular statistics is being calculated
    *

include/dem/explicit_euler_integrator.h

@@ -16,6 +16,8 @@ using namespace dealii;
  * also integrated into integration class
  *
  * @note Euler is a first-order integration scheme. Calculation proceudre:
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  *
  * x(n+1) = x(n) + v(n) * dt
  * v(n+1) = v(n) + a(n) * dt

include/dem/find_contact_detection_step.h

@@ -15,7 +15,9 @@ using namespace dealii;
 
 /**
  * @brief Find steps for dynamic contact search for particle-particle contacts.
- *
+
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  * @param particle_handler
  * @param dt DEM time step
  * @param smallest_contact_search_criterion A criterion for finding

include/dem/force_chains_visualization.h

@@ -25,12 +25,14 @@ using namespace dealii;
 using namespace DEM;
 
 /**
- * Base class for the particles force chains contact force models.
+ * @brief Base class for the particles force chains contact force models.
  * This class does not implement any of the models, but ensures that
  * an interface without template specialization is available. All of the
  * actual implementation of the models are carried out in the
  * ParticlesForceChains class which is templated by the contact model
  * type.
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  */
 template <int dim, DEM::SolverType solver_type>
 class ParticlesForceChainsBase

include/dem/integrator.h

@@ -16,6 +16,8 @@ using namespace dealii;
 /**
  * @brief Base interface for classes that carry out the integration of the velocity and
  * position of particles with inertia
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  */
 template <int dim, DEM::SolverType solver_type>
 class Integrator

include/dem/lagrangian_post_processing.h

@@ -31,6 +31,9 @@ using namespace dealii;
 /**
  * @brief Carries out writing the cell data of the domain.
  *
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
+ *
  * @param triangulation Triangulation of the domain.
  * @param grid_pvdhandler PVD handler for grid.
  * @param background_dh Background DoF handler.

include/dem/load_balancing.h

@@ -20,6 +20,9 @@ using namespace dealii;
  * @brief Manages the load balancing (repartitioning), of the domain according
  * to the computational load of the cells and the particles.
  * It is used by the DEM and the coupling CFD-DEM solvers.
+ *
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  */
 template <int dim, DEM::SolverType solver_type>
 class LagrangianLoadBalancing

include/dem/particle_particle_broad_search.h

@@ -57,6 +57,9 @@ find_particle_particle_contact_pairs(
  * This version of the function is used when adaptive sparse contacts is
  * enabled.
  *
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
+ *
  * @param particle_handler The particle handler of particles in the broad
  * search
  * @param[in] cells_local_neighbor_list  A vector (with size equal to the number

include/dem/particle_particle_contact_force.h

@@ -29,6 +29,8 @@ using namespace dealii;
  * actual implementation of the models are carried out in the
  * ParticleParticleContactForce class which is templated by the contact model
  * type.
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  */
 template <int dim, DEM::SolverType solver_type>
 class ParticleParticleContactForceBase

include/dem/particle_point_line_broad_search.h

@@ -44,6 +44,9 @@ find_particle_point_contact_pairs(
  * collision pairs will be investigated in the fine search to check if they
  * are in contact or not.
  *
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
+ *
  * @param particle_handler Particle handler of particles located in boundary
  * cells.
  * @param boundary_cells_with_points A container of cells which are located at

include/dem/particle_point_line_contact_force.h

@@ -21,6 +21,9 @@ using namespace dealii;
  * of particles and walls. Since the inputs and the calculation method of
  * particle-point and particle-line contact forces are similar, we only used one
  * function for both tasks.
+ *
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  */
 template <int dim, DEM::SolverType solver_type>
 class ParticlePointLineForce

include/dem/particle_point_line_fine_search.h

@@ -14,6 +14,9 @@ using namespace dealii;
  * contact, the normal overlap, normal vector of contact and contact normal
  * relative velocity are stored in a map which is the output of this function.
  *
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
+ *
  * @param particle_point_contact_candidates The output of particle-point broad
  * search which shows contact pair candidates.
  * @param neighborhood_threshold A value which defines the neighbor particles.

include/dem/particle_wall_broad_search.h

@@ -45,6 +45,25 @@ find_particle_wall_contact_pairs(
   typename DEM::dem_data_structures<dim>::particle_wall_candidates
     &particle_wall_contact_candidates);
 
+/**
+ * @brief Finds unordered map of tuples (tuple of particle located in
+ * boundary cells, normal vector of the boundary face, a
+ * point on the face and the corresponding boundary cell) which shows the
+ * candidate particle-wall collision pairs. These collision candidates will be
+ * investigated in the fine search to check if they are in contact or not.
+ *
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
+ *
+ * @param boundary_cells_information Information of the boundary cells and
+ * faces. This is the output of the FindBoundaryCellsInformation class.
+ * @param particle_handler Particle handler of particles located in boundary
+ * cells.
+ * @param particle_wall_contact_candidates A two-layered unordered map of tuples. Each
+ * tuple contains a particle located near boundaries, the normal vector of
+ * the corresponding face boundary, a point on the boundary and the boundary
+ * cell. The contact pair is used in the fine search.
+ */
 template <int dim, DEM::SolverType solver_type>
 void
 find_particle_wall_contact_pairs(
@@ -85,6 +104,26 @@ find_particle_floating_wall_contact_pairs(
   typename DEM::dem_data_structures<dim>::particle_floating_wall_candidates
     &particle_floating_wall_candidates);
 
+/**
+ * @brief Find a two-layered unordered map of particle iterators which shows the
+ * candidate particle-floating wall collision candidates. These collision
+ * pairs will be investigated in the fine search to check if they are in
+ * contact or not
+ *
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
+ *
+ * @param boundary_cells_for_floating_walls Boundary cells located adjacent to
+ * floating walls
+ * @param particle_handler Particle handler of particles located in boundary
+ * cells
+ * @param floating_wall_properties Properties of the floating walls specified
+ * in the parameter handler file
+ * @param simulation_time Simulation time
+ * @param particle_floating_wall_candidates Output of particle-floating wall
+ * broad search which contains all the particle-floating wall collision
+ * candidates
+ */
 template <int dim, DEM::SolverType solver_type>
 void
 find_particle_floating_wall_contact_pairs(
@@ -127,6 +166,27 @@ particle_solid_surfaces_contact_search(
   typename DEM::dem_data_structures<dim>::cells_total_neighbor_list
     &cells_total_neighbor_list);
 
+
+/**
+ * @brief Find a two-layered unordered map
+ * (particle_floating_mesh_contact_candidates) of particle iterators that
+ * shows the candidate particle-floating mesh collision candidates. These
+ * collision pairs will be investigated in the fine search to check if they
+ * are in contact or not
+ *
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
+ *
+ * @param solid_surfaces_mesh_information Information of the solid surfaces mapped
+ * in the background triangulation.
+ * @param particle_handler
+ * @param particle_floating_mesh_contact_candidates Particle-floating mesh contact
+ * candidates
+ * @param cells_total_neighbor_list A container in which all the neighbor cells
+ * of the local cells are stored
+ * @param sparse_contacts_object The object that contains the
+ * information about the mobility status of cells
+ */
 template <int dim, DEM::SolverType solver_type>
 void
 particle_solid_surfaces_contact_search(

include/dem/particle_wall_contact_force.h

@@ -23,6 +23,9 @@ using namespace dealii;
 /**
  * @brief Base interface for classes that carry out the calculation of
  * particle-wall contact force.
+
+ * @tparam dim An integer that denotes the number of spatial dimensions.
+ * @tparam solve_type Type of solver used for the DEM.
  */
 
 template <int dim, DEM::SolverType solver_type>