Review Comments: Increase Documentation

... and remove unused parameters.
ComputationalRadiationPhysics · Dec 8, 2015 · aae709a · aae709a
1 parent 64594d9
commit aae709a
Show file tree

Hide file tree

Showing 8 changed files with 58 additions and 25 deletions.
diff --git a/src/picongpu/include/particles/manipulators/AssignImpl.hpp b/src/picongpu/include/particles/manipulators/AssignImpl.hpp
@@ -40,7 +40,7 @@ struct AssignImpl
         typedef AssignImpl type;
     };
 
-    HINLINE AssignImpl(uint32_t currentStep)
+    HINLINE AssignImpl(uint32_t)
     {
     }
 

diff --git a/src/picongpu/include/particles/manipulators/DriftImpl.hpp b/src/picongpu/include/particles/manipulators/DriftImpl.hpp
@@ -40,9 +40,8 @@ struct DriftImpl : private T_ValueFunctor
 
     typedef T_ValueFunctor ValueFunctor;
 
-    HINLINE DriftImpl(uint32_t currentStep)
+    HINLINE DriftImpl(uint32_t)
     {
-
     }
 
     template<typename T_Particle1, typename T_Particle2>

diff --git a/src/picongpu/include/particles/manipulators/FreeImpl.hpp b/src/picongpu/include/particles/manipulators/FreeImpl.hpp
@@ -43,9 +43,8 @@ struct FreeImpl
         typedef FreeImpl<T_Functor> type;
     };
 
-    HINLINE FreeImpl(uint32_t currentStep)
+    HINLINE FreeImpl(uint32_t)
     {
-
     }
 
     template<typename T_Particle1, typename T_Particle2>

diff --git a/src/picongpu/include/particles/manipulators/NoneImpl.hpp b/src/picongpu/include/particles/manipulators/NoneImpl.hpp
@@ -38,7 +38,7 @@ struct NoneImpl
         typedef NoneImpl type;
     };
 
-    HINLINE NoneImpl(uint32_t currentStep)
+    HINLINE NoneImpl(uint32_t)
     {
     }
 

diff --git a/src/picongpu/include/particles/manipulators/ProtonTimesWeightingImpl.def b/src/picongpu/include/particles/manipulators/ProtonTimesWeightingImpl.def
@@ -37,6 +37,11 @@ namespace manipulators
  * of the new species' macro particles to be a multiplied by
  * the number of protons on the initial species.
  *
+ * As an example, this comes useful when initializing a quasi-neutral,
+ * pre-ionized plasma of ions and electrons. Electrons can be created
+ * from ions via cloning and increasing their weight to avoid simulating
+ * multiple macro electrons per macro ion (with Z>1).
+ *
  * note: needs the atomicNumbers flag on the initial species,
  *       used by the GetAtomicNumbers trait.
  */

diff --git a/src/picongpu/include/particles/manipulators/ProtonTimesWeightingImpl.hpp b/src/picongpu/include/particles/manipulators/ProtonTimesWeightingImpl.hpp
@@ -42,20 +42,33 @@ struct ProtonTimesWeightingImpl
         typedef ProtonTimesWeightingImpl type;
     };
 
-    HINLINE ProtonTimesWeightingImpl(uint32_t currentStep)
+    HINLINE ProtonTimesWeightingImpl(uint32_t)
     {
-
     }
 
-    template<typename T_Particle1, typename T_Particle2>
+    /* Increase weighting of particleDest by proton number of SrcParticle
+     *
+     * The frame's `atomicNumber` `numberOfProtons`of `T_SrcParticle`
+     * is used to increase the weighting of particleDest.
+     * Useful to increase the weighting of macro electrons when cloned from an
+     * ion with Z>1. Otherwise one would need Z macro electrons (each with the
+     * same weighting as the initial ion) to keep the charge of a pre-ionized
+     * atom neutral.
+     *
+     * \tparam T_DestParticle type of the particle species with weighting to manipulate
+     * \tparam T_SrcParticle type of the particle species with proton number Z
+     *
+     * \see picongpu::particles::ManipulateCloneSpecies , picongpu::kernelCloneParticles
+     */
+    template<typename T_DestParticle, typename T_SrcParticle>
     DINLINE void operator()(const DataSpace<simDim>&,
-                            T_Particle1& particleSpecies1, T_Particle2&,
-                            const bool isParticle1, const bool isParticle2)
+                            T_DestParticle& particleDest, T_SrcParticle&,
+                            const bool isDestParticle, const bool isSrcParticle)
     {
-        if (isParticle1 && isParticle2)
+        if (isDestParticle && isSrcParticle)
         {
-            const float_X protonNumber = traits::GetAtomicNumbers<T_Particle2>::type::numberOfProtons;
-            particleSpecies1[weighting_] *= protonNumber;
+            const float_X protonNumber = traits::GetAtomicNumbers<T_SrcParticle>::type::numberOfProtons;
+            particleDest[weighting_] *= protonNumber;
         }
     }
 };

diff --git a/src/picongpu/include/particles/manipulators/RatioWeightingImpl.hpp b/src/picongpu/include/particles/manipulators/RatioWeightingImpl.hpp
@@ -42,24 +42,42 @@ struct RatioWeightingImpl
         typedef RatioWeightingImpl type;
     };
 
-    HINLINE RatioWeightingImpl(uint32_t currentStep)
+    HINLINE RatioWeightingImpl(uint32_t)
     {
-
     }
 
-    template<typename T_Particle1, typename T_Particle2>
+    /* Adjust the weighting of particleDes by densityRatio of own & Src particle
+     *
+     * While cloning a particle (particleDes) from an other (T_SrcParticle), one
+     * can afterward directly normalize the weighting back to the intended density:
+     * - divide weighting with the `T_SrcParticle`'s densityRatio
+     *   (to get macro particle weighting according to reference GAS_DENSITY * profile
+     *    at this specific point in space & time)
+     * - multiply weighting with own densityRatio (to get this species'
+     *    densityRatio * GAS_DENSITY * profile)
+     *
+     * This is useful when the profile and number of macro particles for both species
+     * shall be the same and the initialization of an other profile via `CreateGas`
+     * would be expensive (or one wants to keep the exact same position while cloning).
+     *
+     * \tparam T_DesParticle type of the particle species with weighting to manipulate
+     * \tparam T_SrcParticle type of the particle species one cloned from
+     *
+     * \see picongpu::particles::ManipulateCloneSpecies , picongpu::kernelCloneParticles
+     */
+    template<typename T_DesParticle, typename T_SrcParticle>
     DINLINE void operator()(const DataSpace<simDim>&,
-                            T_Particle1& particleSpecies1, T_Particle2&,
-                            const bool isParticle1, const bool isParticle2)
+                            T_DesParticle& particleDes, T_SrcParticle&,
+                            const bool isDesParticle, const bool isSrcParticle)
     {
-        if (isParticle1 && isParticle2)
+        if (isDesParticle && isSrcParticle)
         {
             const float_X densityRatioDes =
-                traits::GetDensityRatio<T_Particle1>::type::getDefaultValue();
+                traits::GetDensityRatio<T_DesParticle>::type::getDefaultValue();
             const float_X densityRatioSrc =
-                traits::GetDensityRatio<T_Particle2>::type::getDefaultValue();
+                traits::GetDensityRatio<T_SrcParticle>::type::getDefaultValue();
 
-            particleSpecies1[weighting_] *= densityRatioDes / densityRatioSrc;
+            particleDes[weighting_] *= densityRatioDes / densityRatioSrc;
         }
     }
 };

diff --git a/src/picongpu/include/particles/manipulators/SetAttributeImpl.hpp b/src/picongpu/include/particles/manipulators/SetAttributeImpl.hpp
@@ -39,9 +39,8 @@ struct SetAttributeImpl : private T_ValueFunctor
 
     typedef T_ValueFunctor ValueFunctor;
 
-    HINLINE SetAttributeImpl(uint32_t currentStep)
+    HINLINE SetAttributeImpl(uint32_t)
     {
-
     }
 
     template<typename T_Particle1, typename T_Particle2>