Parameter void fraction smoothing length redefinition (#1408)

Description
Change name and meaning of the void fraction smoothing length factor parameter for unresolved CFD-DEM and VANS simulations. The previous parameters, named "l2 smoothing factor", meant the square of the desired smoothing length. The new parameter, named "l2 smoothing length", is the actual length of the smoothing region. This was done by adding an attribute to the void fraction class (l2_smoothing_factor) calculated as the parameter's square. This way, the meaning of the parameter are more understandable and more easily manipulated.

Testing
l2 smoothing lengths were calculated as square root of the previous ones, and all tests pass.

CHANGELOG.md

@@ -5,13 +5,17 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ## [Master] - 2025-01-20
 
+### Changed
+
+- MAJOR This change deprecates the "l2 smoothing factor" void fraction parameter and introduces the "l2 smoothing factor length". The previous parameters, named "l2 smoothing factor", meant the square of the desired smoothing length. The new parameter, named "l2 smoothing length", is the actual length of the smoothing region. This was done by adding an attribute to the void fraction class (l2_smoothing_factor) calculated as the parameter's square. This way, the meaning of the parameter are more understandable and more easily manipulated. [#1408](https://github.com/chaos-polymtl/lethe/pull/1408)
+
 ### Fixed
 
 - MAJOR The change in #1406 introduced a major bug that would prevent the velocity, diameter, angular velocity and other particle properties from being adequately displayed in paraview. This PR fixes this bug by adequately positioning the output data when building the patches. [#1407](https://github.com/chaos-polymtl/lethe/pull/1407)
 
 ## [Master] - 2025-01-17
 
-### Change
+### Changed
 
 - MAJOR The order of the particle properties used for DEM and CFD-DEM has been changed. The mass is now the third property (index 2) instead of being the last. This change, which is purely esthetic, allowed us to fix a leftover bug in the visualisation of DEM results where the array allocated for the particle properties in the VTU output was not the right size (it was one double too small). Surprisingly, this was not crashing, but it was wrong in any cases. Furthermore, we figured out that some of the restart CFD-DEM application tests (the particle sedimentation and the gas fluidized bed) had wrong restart files. This PR addresses all of those changes and refreshes the restart files due to the change in the order of the particle properties. [#1406](https://github.com/chaos-polymtl/lethe/pull/1406)
 

applications_tests/lethe-fluid-particles/adaptive_sparse_contacts.prm

@@ -163,7 +163,7 @@ subsection void fraction
   set mode                = qcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.0001
+  set l2 smoothing length = 0.01
 end
 
 # --------------------------------------------------

applications_tests/lethe-fluid-particles/dynamic_contact_search.prm

@@ -72,7 +72,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.00001
+  set l2 smoothing length = 0.00316227766
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-particles/generators/gas_solid_fluidized_bed_generator_step_2_cfd-dem.prm

@@ -79,7 +79,7 @@ subsection void fraction
   set mode                = qcm
   set read dem            = true
   set dem file name       = ../restart_fluidized_bed_files/dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-particles/generators/restart_particle_sedimentation_generator.prm

@@ -71,7 +71,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = ../particle_sedimentation_files/dem
-  set l2 smoothing factor = 0.00001
+  set l2 smoothing length = 0.00316227766
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-particles/liquid_fluidized_bed.prm

@@ -74,7 +74,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.00000125
+  set l2 smoothing length = 0.001118033989
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-particles/particle_sedimentation.prm

@@ -72,7 +72,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.00001
+  set l2 smoothing length = 0.00316227766
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-particles/periodic_particles_qcm.prm

@@ -145,7 +145,7 @@ subsection void fraction
   set mode                = qcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.0005
+  set l2 smoothing length = 0.02236067977
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-particles/periodic_particles_qcm_opposite_flow.prm

@@ -145,7 +145,7 @@ subsection void fraction
   set mode                = qcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.0005
+  set l2 smoothing length = 0.02236067977
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-particles/restart_gas_solid_fluidized_bed.prm

@@ -77,7 +77,7 @@ subsection void fraction
   set mode                = qcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-particles/restart_particle_sedimentation.prm

@@ -72,7 +72,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.00001
+  set l2 smoothing length = 0.00316227766
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-vans/beetstra_packed_bed.prm

@@ -78,7 +78,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-vans/dallavalle_packed_bed.prm

@@ -78,7 +78,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-vans/difelice_packed_bed.prm

@@ -78,7 +78,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-vans/gidaspow_packed_bed.prm

@@ -78,7 +78,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-vans/kochhill_packed_bed.prm

@@ -78,7 +78,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-vans/pcm_packed_bed.prm

@@ -78,7 +78,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-vans/qcm_packed_bed.prm

@@ -79,7 +79,7 @@ subsection void fraction
   set qcm sphere equal cell volume = false
   set read dem                     = true
   set dem file name                = dem
-  set l2 smoothing factor          = 0
+  set l2 smoothing length          = 0
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-vans/rong_packed_bed.prm

@@ -78,7 +78,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

applications_tests/lethe-fluid-vans/spm_packed_bed.prm

@@ -78,7 +78,7 @@ subsection void fraction
   set mode                = spm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

doc/source/examples/unresolved-cfd-dem/cylindrical-packed-bed/cylindrical-packed-bed.rst

@@ -296,15 +296,15 @@ The additional sections that define the VANS solver are the void fraction subsec
 Void Fraction
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Since we are calculating the void fraction using the packed bed of the DEM simulation, we set the mode to ``dem``. For this, we need to read the dem files which we already wrote using check-pointing. We therefore set the read dem to ``true`` and specify the prefix of the ``dem`` files to be read. We now choose a smoothing factor for the void fraction as to reduce discontinuity which can lead to oscillations in the velocity. The factor we choose is around the square of twice the particle's diameter. 
+Since we are calculating the void fraction using the packed bed of the DEM simulation, we set the mode to ``dem``. For this, we need to read the dem files which we already wrote using check-pointing. We therefore set the read dem to ``true`` and specify the prefix of the ``dem`` files to be read. We now choose a smoothing length for the void fraction as to reduce discontinuity which can lead to oscillations in the velocity. The length we choose is around the square of twice the particle's diameter. 
 
 .. code-block:: text
 
     subsection void fraction
       set mode                = pcm
       set read dem            = true
       set dem file name       = dem
-      set l2 smoothing factor = 0.000005
+      set l2 smoothing length = 0.002236067977
     end
 
 CFD-DEM

doc/source/examples/unresolved-cfd-dem/dense-pneumatic-conveying/dense-pneumatic-conveying.rst

@@ -503,15 +503,15 @@ By default, the controller has a high stiffness and aims to correct the flow in
 Void Fraction
 -------------
 
-We choose the `quadrature centred method (QCM) <../../../theory/multiphase/cfd_dem/unresolved_cfd-dem.html#the-quadrature-centered-method>`_  to calculate the void fraction. The ``l2 smoothing factor`` we choose is the square of twice the diameter of the particles.
+We choose the `quadrature centred method (QCM) <../../../theory/multiphase/cfd_dem/unresolved_cfd-dem.html#the-quadrature-centered-method>`_  to calculate the void fraction. The ``l2 smoothing length`` we choose is of twice the diameter of the particles.
 
 .. code-block:: text
 
     subsection void fraction
       set mode                = qcm
       set read dem            = true
       set dem file name       = dem
-      set l2 smoothing factor = 0.0001
+      set l2 smoothing length = 0.01
     end
 
 CFD-DEM
@@ -663,4 +663,4 @@ References
 
 .. [#lavrinec2021] \A. Lavrinec, O. Orozovic, H. Rajabnia, K. Williams, M. Jones & G. Klinzing, “An assessment of steady-state conditions in single slug horizontal pneumatic conveying.” *Particuology*, vol. 58, pp. 187-195, 2021. doi: `10.1016/j.partic.2021.04.007 <https://doi.org/10.1016/j.partic.2021.04.007>`_\.
 
-.. [#lavrinec2020] \A. Lavrinec, O. Orozovic, H. Rajabnia, K. Williams, M. Jones et G. Klinzing, “Velocity and porosity relationships within dense phase pneumatic conveying as studied using coupled CFD-DEM.” *Powder Technology*, vol. 375, pp. 89–100, 2020. doi: `10.1016/j.powtec.2020.07.070 <https://doi.org/10.1016/j.powtec.2020.07.070>`_\.
+.. [#lavrinec2020] \A. Lavrinec, O. Orozovic, H. Rajabnia, K. Williams, M. Jones et G. Klinzing, “Velocity and porosity relationships within dense phase pneumatic conveying as studied using coupled CFD-DEM.” *Powder Technology*, vol. 375, pp. 89–100, 2020. doi: `10.1016/j.powtec.2020.07.070 <https://doi.org/10.1016/j.powtec.2020.07.070>`_\.

doc/source/examples/unresolved-cfd-dem/gas-solid-fluidized-bed/gas-solid-fluidized-bed.rst

@@ -308,15 +308,15 @@ The additional sections for the CFD-DEM simulations are the void fraction subsec
 Void Fraction
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Since we are calculating the void fraction using the packed bed of the DEM simulation, we set the mode to "dem". For this, we need to read the dem files which we already wrote using check-pointing. We, therefore, set the read dem to "true" and specify the prefix of the dem files to be dem. We now choose a smoothing factor for the void fraction to reduce discontinuity which can lead to oscillations in the velocity. The factor we choose is around the square of twice the particle's diameter. 
+Since we are calculating the void fraction using the packed bed of the DEM simulation, we set the mode to "dem". For this, we need to read the dem files which we already wrote using check-pointing. We, therefore, set the read dem to "true" and specify the prefix of the dem files to be dem. We now choose a smoothing length for the void fraction to reduce discontinuity which can lead to oscillations in the velocity. The length we choose is around the square of twice the particle's diameter. 
 
 .. code-block:: text
 
     subsection void fraction
         set mode                = pcm
         set read dem            = true
         set dem file name       = dem
-        set l2 smoothing factor = 0.000005
+        set l2 smoothing length = 0.02236067977
     end
 
 CFD-DEM

doc/source/examples/unresolved-cfd-dem/liquid-solid-fluidized-bed/liquid-solid-fluidized-bed.rst

@@ -321,15 +321,15 @@ The following sections for the CFD-DEM simulations are the void fraction subsect
 Void Fraction
 ~~~~~~~~~~~~~~~
 
-We choose the `particle centroid method (PCM) <../../../parameters/unresolved-cfd-dem/void-fraction.html>`_ to calculate void fraction. The ``l2 smoothing factor`` we choose is around the square of twice the particle’s diameter, as in the other examples.
+We choose the `particle centroid method (PCM) <../../../parameters/unresolved-cfd-dem/void-fraction.html>`_ to calculate void fraction. The ``l2 smoothing length`` we choose is around twice the particle’s diameter, as in the other examples.
 
 .. code-block:: text
 
     subsection void fraction
       set mode                = pcm
       set read dem            = true
       set dem file name       = dem
-      set l2 smoothing factor = 2.8387584e-5
+      set l2 smoothing length = 0.005328
     end
 
 
@@ -491,4 +491,4 @@ References
 
 .. [#ferreira2023b] \V. O. Ferreira, D. Silva Junior, K. R. B. de Melo, B. Blais, and G. C. Lopes, “Prediction of the bed expansion of a liquid fluidized bed bioreactor applied to wastewater treatment and biogas production,” *Energy Convers. Manag.*, vol. 290, pp. 117224, Aug. 2023, doi: `10.1016/j.enconman.2023.117224 <https://doi.org/10.1016/j.enconman.2023.117224>`_\.
 
-.. [#yang2003] \W.-C. Yang, Ed., *Handbook of Fluidization and Fluid-Particle Systems*, 1st ed. Boca Raton: CRC Press, 2003. doi: `10.1201/9780203912744 <https://doi.org/10.1201/9780203912744>`_\.
+.. [#yang2003] \W.-C. Yang, Ed., *Handbook of Fluidization and Fluid-Particle Systems*, 1st ed. Boca Raton: CRC Press, 2003. doi: `10.1201/9780203912744 <https://doi.org/10.1201/9780203912744>`_\.

doc/source/parameters/unresolved-cfd-dem/void-fraction.rst

@@ -9,7 +9,7 @@ In this subsection, all parameters required for the calculation of the void frac
     set mode                       = pcm
     set read dem                   = true
     set dem file name              = dem
-    set l2 smoothing factor        = 0
+    set l2 smoothing length        = 0
     set particle refinement factor = 0
   end
 
@@ -34,7 +34,7 @@ If the ``mode`` chosen is ``pcm``, then the void fraction is calculated using th
 
 * The ``read dem`` allows us to read an already existing dem simulation result which can be obtained from checkpointing the Lethe-DEM simulation. This is important as the `lethe-fluid-vans` solver requires reading an initial dem triangulation and particle information to simulate flows in the presence of particles. 
 * The ``dem_file_name`` parameter specifies the prefix of the dem files that must be read.
-* The ``l2 smoothing factor`` is a smoothing length used for smoothing the L2 projection of the void fraction to avoid sharp discontinuities which can lead to instabilities in the simulation.
+* The ``l2 smoothing length`` is a smoothing length used for smoothing the L2 projection of the void fraction to avoid sharp discontinuities which can lead to instabilities in the simulation.
 * The ``qcm sphere diameter`` allows us to fix the diameter of all reference spheres in the simulation to a given value. If this option is used (a value other than 0 is specified), it overrides the default calculation of the size of the sphere and sets its diameter to the value specified.
 * The ``qcm sphere equal cell volume`` determines whether or not we want to use a reference sphere with the same volume as the element in which it is located. If it is disabled, then each sphere will have a radius equal to the size of the element in which it is located. This parameter is important only when the ``qcm sphere diameter`` is not used or is set to 0.
 * The ``particle refinement factor`` is only required for the ``spm``. It allows to determine the number of pseudo-particles that we want to divide our particle into. By default, it is set to 0 refinements, and results in no refinement of the original meshed particle (division into 7 particles in 3D). Every additional refinement results in a :math:`2^{dim}` times more particles. The figure below shows how the number of pseudo-particles change with every refinement. Every cell in the particle mesh represents a pseudo-particle in the satellite point method.

examples/unresolved-cfd-dem/cylindrical-packed-bed/flow-in-bed.prm

@@ -54,7 +54,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.00001
+  set l2 smoothing length = 0.00316227766
 end
 
 #---------------------------------------------------

examples/unresolved-cfd-dem/dense-pneumatic-conveying/pneumatic-conveying.prm

@@ -140,7 +140,7 @@ subsection void fraction
   set mode                = qcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.0001
+  set l2 smoothing length = 0.01
 end
 
 #---------------------------------------------------

examples/unresolved-cfd-dem/gas-solid-fluidized-bed/gas-solid-fluidized-bed.prm

@@ -57,7 +57,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000005
+  set l2 smoothing length = 0.0022360679774998
 end
 
 #---------------------------------------------------

examples/unresolved-cfd-dem/liquid-solid-fluidized-bed/liquid-solid-fluidized-bed.prm

@@ -60,7 +60,7 @@ subsection void fraction
   set mode                = pcm
   set read dem            = true
   set dem file name       = dem
-  set l2 smoothing factor = 0.000028387584
+  set l2 smoothing length = 0.05623413252
 end
 
 #---------------------------------------------------

include/fem-dem/parameters_cfd_dem.h

@@ -68,7 +68,7 @@ namespace Parameters
     Functions::ParsedFunction<dim> void_fraction;
     bool                           read_dem;
     std::string                    dem_file_name;
-    double                         l2_smoothing_factor;
+    double                         l2_smoothing_length;
     unsigned int                   particle_refinement_factor;
     double                         qcm_sphere_diameter;
     bool                           qcm_sphere_equal_cell_volume;

include/fem-dem/void_fraction.h

@@ -11,6 +11,7 @@
 #include <fem-dem/parameters_cfd_dem.h>
 
 #include <deal.II/base/index_set.h>
+#include <deal.II/base/utilities.h>
 
 #include <deal.II/distributed/tria_base.h>
 
@@ -390,6 +391,10 @@ class VoidFractionBase : public PhysicsLinearSubequationsSolver
   std::map<unsigned int,
            std::set<typename DoFHandler<dim>::active_cell_iterator>>
     vertices_to_periodic_cell;
+
+  // Smoothing length factor for the void fraction calculation
+  const double l2_smoothing_factor =
+    Utilities::fixed_power<2>(void_fraction_parameters->l2_smoothing_length);
 };
 
 

source/fem-dem/parameters_cfd_dem.cc

@@ -26,10 +26,10 @@ namespace Parameters
                       "dem",
                       Patterns::FileName(),
                       "File output dem prefix");
-    prm.declare_entry("l2 smoothing factor",
-                      "0.000001",
+    prm.declare_entry("l2 smoothing length",
+                      "0.001",
                       Patterns::Double(),
-                      "The smoothing factor for void fraction L2 projection");
+                      "The smoothing length for void fraction L2 projection");
     prm.declare_entry(
       "particle refinement factor",
       "0",
@@ -70,7 +70,7 @@ namespace Parameters
 
     read_dem                   = prm.get_bool("read dem");
     dem_file_name              = prm.get("dem file name");
-    l2_smoothing_factor        = prm.get_double("l2 smoothing factor");
+    l2_smoothing_length        = prm.get_double("l2 smoothing length");
     particle_refinement_factor = prm.get_integer("particle refinement factor");
     qcm_sphere_diameter        = prm.get_double("qcm sphere diameter");
     qcm_sphere_equal_cell_volume = prm.get_bool("qcm sphere equal cell volume");