Fixed some design notes after review

ComputationalRadiationPhysics · Jul 27, 2020 · be717f7 · be717f7
1 parent 5440598
commit be717f7
Show file tree

Hide file tree

Showing 5 changed files with 26 additions and 22 deletions.
diff --git a/docs/TBG_macros.cfg b/docs/TBG_macros.cfg
@@ -144,8 +144,8 @@ TBG_<species>_pngYX="--<species>_png.period 10 --<species>_png.axis yx --<specie
 # Enable macro particle merging
 TBG_<species>_merger="--<species>_merger.period 100 --<species>_merger.minParticlesToMerge 8 --<species>_merger.posSpreadThreshold 0.2 --<species>_merger.absMomSpreadThreshold 0.01"
 
-# Enable probalistic version of particle merging
-TBG_<species>_randomizedMerger="--<species>_randomizedMerger.period 100 --<species>_randomizedMerger.minParticlesToMerge 8 --<species>_randomizedMerger.ratioDeletedParticles 0.9"
+# Enable probabilistic version of particle merging
+TBG_<species>_randomizedMerger="--<species>_randomizedMerger.period 100 --<species>_randomizedMerger.maxParticlesToMerge 8 --<species>_randomizedMerger.ratioDeletedParticles 0.9"
 
 # Notification period of position plugin (single-particle debugging)
 TBG_<species>_pos_dbg="--<species>_position.period 1"

diff --git a/...age/plugins/particleMergerProbalistic.rst → ...e/plugins/particleMergerProbabilistic.rst b/...age/plugins/particleMergerProbalistic.rst → ...e/plugins/particleMergerProbabilistic.rst
@@ -1,11 +1,11 @@
-.. _usage-plugins-particleMergerProbalistic:
+.. _usage-plugins-particleMergerProbabilistic:
 
-Particle Merger Probalistic version
------------------------------------
+Particle Merger Probabilistic Version
+-------------------------------------
 
 Merges macro particles that are close in phase space to reduce computational load.
 Voronoi-based probalistic variative algorithm. The difference between Base Voronoi algorothm
-and probalistic Version in parameters: instead of threshold of spread in position and momentum
+and probabilistic version in parameters: instead of threshold of spread in position and momentum
 use ratio of deleted particles. 
 
 
@@ -29,9 +29,13 @@ PIConGPU command line option                 Description
 ============================================ ================================================================================================================
 ``--<species>_merger.period``                The ouput periodicity of the plugin. A value of ``100`` would mean an output at simulation time step *0, 100, 200, ...*.
 
-``--<species>_merger.ratioOfDeletedParticles``  The ratio of particles to delete. The parameter have to be in Range *[0:1]*
+``--<species>_merger.ratioOfDeletedParticles`` The ratio of particles to delete. The parameter have to be in Range *[0:1]*.
 
-``--<species>_merger.minParticlesToMerge``   minimal number of macroparticles can be merged into a single macroparticle.
+``--<species>_merger.maxParticlesToMerge``   Maximum number of macroparticles that can be merged into a single macroparticle.
+
+``--<species>_merger.posSpreadThreshold``    Below this threshold of spread in position macroparticles can be merged [unit: cell edge length].
+
+``--<species>_merger.momSpreadThreshold``    Below this absolute threshold of spread in momentum macroparticles can be merged [unit: :math:`m_{e-} \cdot c`].
 ============================================ ================================================================================================================
 
 Memory Complexity

diff --git a/include/picongpu/plugins/randomizedParticleMerger/RandomizedParticleMerger.hpp b/include/picongpu/plugins/randomizedParticleMerger/RandomizedParticleMerger.hpp
@@ -77,7 +77,7 @@ namespace randomizedParticleMerger
         std::string notifyPeriod;
         MappingDesc* cellDescription;
 
-        uint32_t minMacroParticlesToDivide;
+        uint32_t maxParticlesToMerge;
         float_X ratioDeletedParticles;
         float_X posSpreadThreshold;
         float_X momSpreadThreshold;
@@ -131,7 +131,7 @@ namespace randomizedParticleMerger
             RngFactory rngFactory(currentStep);
             auto kernel = Kernel{
                 particles->getDeviceParticlesBox(),
-                minMacroParticlesToDivide,
+                maxParticlesToMerge,
                 ratioDeletedParticles,
                 posSpreadThreshold,
                 momSpreadThreshold,
@@ -169,11 +169,11 @@ namespace randomizedParticleMerger
                 "enable plugin [for each n-th step]"
             )
             (
-                ( prefix + ".minMacroParticlesToDivide" ).c_str(),
+                ( prefix + ".maxParticlesToMerge" ).c_str(),
                 po::value< uint32_t > (
-                    &minMacroParticlesToDivide
+                    &maxParticlesToMerge
                 )->default_value( 8 ),
-                "minimum number of macro particles at which we always divide the cell"
+                "minimum number of macroparticles at which we always divide the cell"
             )
             (
                 ( prefix + ".posSpreadThreshold" ).c_str(),
@@ -190,7 +190,6 @@ namespace randomizedParticleMerger
                 )->default_value( 1e-5 ),
                 "Below this absolute threshold of spread in momentum"
                 " macroparticles can be merged [unit: m_el * c]."
-                " Disabled for -1 (default)"
             )
              (
                 ( prefix + ".ratioDeletedParticles" ).c_str(),
@@ -219,8 +218,8 @@ namespace randomizedParticleMerger
             );
 
             PMACC_VERIFY_MSG(
-                minMacroParticlesToDivide > 1u,
-                std::string("[Plugin: ") + prefix + "] minMacroParticlesToDivide"
+                maxParticlesToMerge > 1u,
+                std::string("[Plugin: ") + prefix + "] maxParticlesToMerge"
                 " has to be greater than one."
             );
             PMACC_VERIFY_MSG(

diff --git a/include/picongpu/plugins/randomizedParticleMerger/RandomizedParticleMerger.kernel b/include/picongpu/plugins/randomizedParticleMerger/RandomizedParticleMerger.kernel
@@ -70,7 +70,7 @@ namespace randomizedParticleMerger
         ParticlesBox particlesBox;
         /** minimal number of macroparticles needed to divide
             the macroparticle collection  */
-        uint32_t minMacroParticlesToDivide;
+        uint32_t maxParticlesToMerge;
 
         pmacc::math::Int<simDim> guardSuperCells;
         /** estimated fraction of macroparticles
@@ -90,15 +90,15 @@ namespace randomizedParticleMerger
 
         RandomizedParticleMergerKernel(
             ParticlesBox particlesBox,
-            uint32_t minMacroParticlesToDivide,
+            uint32_t maxParticlesToMerge,
             float_X ratioDeletedParticles,
             float_X posSpreadThreshold,
             float_X momSpreadThreshold,
             RngFactory rngFactory,
             const pmacc::math::Int<simDim> guardSuperCells
         ) :
             particlesBox( particlesBox ),
-            minMacroParticlesToDivide( minMacroParticlesToDivide ),
+            maxParticlesToMerge( maxParticlesToMerge ),
             ratioKeptParticles ( 1.0_X - ratioDeletedParticles ),
             posSpreadThreshold ( posSpreadThreshold ),
             momSpreadThreshold ( momSpreadThreshold ),
@@ -216,7 +216,7 @@ namespace randomizedParticleMerger
         ) const
         {
             // With large enough number of macroparticles we always subdivide
-            if ( voronoiCell.numMacroParticles > minMacroParticlesToDivide )
+            if ( voronoiCell.numMacroParticles > maxParticlesToMerge )
                 return true;
 
             // Otherwise we compute subdivision probability based on the parameters
@@ -447,7 +447,7 @@ namespace randomizedParticleMerger
                        break;
                     }
                     voronoiCell.finalizePrecalculationValues(
-                        minMacroParticlesToDivide,
+                        maxParticlesToMerge,
                         ratioKeptParticles
                     );
 

diff --git a/include/picongpu/plugins/randomizedParticleMerger/VoronoiCell.hpp b/include/picongpu/plugins/randomizedParticleMerger/VoronoiCell.hpp
@@ -259,7 +259,6 @@ namespace randomizedParticleMerger
             }
             else
             {
-                // TODO: this equation works, but there may be a better one (see the notebook)
                 float_X undividedCellCoeff = (
                     parentExpectedNumMacroParticles + parentNumMacroParticles ) / 2.0_X;
                 float_X currentExpectedNumMacroParticles =
@@ -293,6 +292,8 @@ namespace randomizedParticleMerger
          * @param minMacroParticlesToDivide min number of macroparticles in a cell
          *                                  such that the cell is always subdivided
          * @param ratioKeptParticles ratio of particles that are kept on average
+         * @return maximum spread value
+         * @return component of most spread in position (as function parameter)
          */
 
         /** auxillary function for getting the mean squared deviation in position or momentum */