FieldTmp Operations: Doxygen Strings

Adds doxygen strings to the classes that users need to define
`FieldTmp` operations in `fileOutput.param` or algorithms such
as Thomas Fermi. This can help to understand how to use those
and can be more detailed then the small examples we give in
`fileOutput.param`.

src/picongpu/include/particles/particleToGrid/ComputeGridValuePerFrame.def

@@ -18,7 +18,14 @@
  * If not, see <http://www.gnu.org/licenses/>.
  */
 
-
+/** @file predefined calculations to derive scalar fields from particles
+ *
+ * The operations in this file derive scalar field quantities from particle
+ * species at runtime, stored temporarily in @see picongpu::FieldTmp for I/O
+ * (@see fileOutput.param) or further usage in algorithms.
+ * Each value is mapped per cell. Some operations are identical up to a
+ * constant, but still provided for convenience.
+ */
 
 #pragma once
 
@@ -30,11 +37,11 @@
 #include <boost/mpl/int.hpp>
 #include <vector>
 
+
 namespace picongpu
 {
 namespace particleToGrid
 {
-
 template<class T_ParticleShape, class T_DerivedAttribute>
 class ComputeGridValuePerFrame
 {
@@ -77,10 +84,17 @@ public:
                             BoxTmp& tmpBox);
 };
 
-/** Predefined Calculations for \see fieldOutput.param
+/** Density Operation for Particle to Grid Projections
+ *
+ * Derives a scalar density field from a particle species at runtime.
+ * Each value is mapped per cell according to the species' spatial shape.
+ *
+ * @tparam T_Species a @see picongpu::Particles class with a species definition,
+ *                   see @see speciesDefinition.param
+ *
+ * @typedef CreateDensityOperation< T_Species >::type a field that can be used
+ *          in @see fileOutput.param @see picongpu::FileOutputFields
  */
-
-/* Density */
 template<typename T_Species>
 struct CreateDensityOperation
 {
@@ -93,7 +107,21 @@ struct CreateDensityOperation
     typedef FieldTmpOperation< ParticleDensity, T_Species > type;
 };
 
-/* ChargeDensity */
+/** Charge Density Operation for Particle to Grid Projections
+ *
+ * Derives a scalar charge density field from a particle species at runtime.
+ * Each value is mapped per cell according to the species' spatial shape.
+ *
+ * @note for species that do not change their charge state, this is identical
+ *       to the density times the (constant) particles' charge,
+ *       @see CreateDensityOperation
+ *
+ * @tparam T_Species a @see picongpu::Particles class with a species definition,
+ *                   see @see speciesDefinition.param
+ *
+ * @typedef CreateChargeDensityOperation< T_Species >::type a field that can be
+ *          used in @see fileOutput.param @see picongpu::FileOutputFields
+ */
 template<typename T_Species>
 struct CreateChargeDensityOperation
 {
@@ -106,7 +134,22 @@ struct CreateChargeDensityOperation
     typedef FieldTmpOperation< ParticleChargeDensity, T_Species > type;
 };
 
-/* MidCurrentDensityComponent */
+/** Current Density Operation for Particle to Grid Projections
+ *
+ * Derives a scalar field with density * charge * velocity_component from a
+ * particle species at runtime.
+ * Each value is mapped per cell according to the species' spatial shape.
+ *
+ * @note Mainly useful for debug purposes, e.g. when implementing a new current
+ *       solver.
+ *
+ * @tparam T_Species a @see picongpu::Particles class with a species definition,
+ *                   see @see speciesDefinition.param
+ *
+ * @typedef CreateMidCurrentDensityComponentOperation< T_Species >::type a field
+ *          that can be used in @see fileOutput.param
+ *          @see picongpu::FileOutputFields
+ */
 template<typename T_Species, typename T_Direction = bmpl::int_<0> >
 struct CreateMidCurrentDensityComponentOperation
 {
@@ -119,7 +162,25 @@ struct CreateMidCurrentDensityComponentOperation
     typedef FieldTmpOperation< ParticleMidCurrentDensityComponent, T_Species > type;
 };
 
-/* ParticleCounter */
+/** Real-Particle Counter Operation for Particle to Grid Projections
+ *
+ * Derives a scalar field with real particle numbers per cell from a particle
+ * species at runtime.
+ * Each macro particle's weighting is assigned straight to the cell it belongs
+ * to, which is in most cases a floor operation in space (and not necessarily
+ * the "nearest" cell-origin).
+ *
+ * @note Use this only for debug purposes, since the deposition "shape" is
+ *       non-physical (inconsistent with charge & momentum-conserving shapes).
+ *       Be aware that this is NOT the same as NGP (0. order shape) assignment
+ *       in a staggered grid.
+ *
+ * @tparam T_Species a @see picongpu::Particles class with a species definition,
+ *                   see @see speciesDefinition.param
+ *
+ * @typedef CreateCounterOperation< T_Species >::type a field that can be used
+ *          in @see fileOutput.param @see picongpu::FileOutputFields
+ */
 template<typename T_Species>
 struct CreateCounterOperation
 {
@@ -131,7 +192,22 @@ struct CreateCounterOperation
     typedef FieldTmpOperation< ParticleCounter, T_Species > type;
 };
 
-/* MacroParticleCounter */
+/** Macro-Particle Counter Operation for Particle to Grid Projections
+ *
+ * Derives a scalar field with number of macro particles per cell from a particle
+ * species at runtime.
+ * Each macro particle is counted straight to the cell it belongs to, which is
+ * in most cases as floor operation in space (and not necessarily the "nearest"
+ * cell-origin).
+ *
+ * @note Use this only for debug purposes, e.g. to validate particle memory.
+ *
+ * @tparam T_Species a @see picongpu::Particles class with a species definition,
+ *                   see @see speciesDefinition.param
+ *
+ * @typedef CreateMacroCounterOperation< T_Species >::type a field that can be
+ *          used in @see fileOutput.param @see picongpu::FileOutputFields
+ */
 template<typename T_Species>
 struct CreateMacroCounterOperation
 {
@@ -143,7 +219,22 @@ struct CreateMacroCounterOperation
     typedef FieldTmpOperation< MacroParticleCounter, T_Species > type;
 };
 
-/* EnergyDensity */
+/** Energy Density Operation for Particle to Grid Projections
+ *
+ * Derives a scalar field for average kinetic particle energy per cell times the
+ * particle density from a particle species at runtime.
+ * Each value is mapped per cell according to the species' spatial shape.
+ *
+ * @note this is the same as the sum of kinetic particle energy
+ *       divided by a constant for the cell volume
+ *       @see CreateEnergyOperation
+ *
+ * @tparam T_Species a @see picongpu::Particles class with a species definition,
+ *                   see @see speciesDefinition.param
+ *
+ * @typedef CreateEnergyDensityOperation< T_Species >::type a field that can be
+ *          used in @see fileOutput.param @see picongpu::FileOutputFields
+ */
 template<typename T_Species>
 struct CreateEnergyDensityOperation
 {
@@ -156,7 +247,21 @@ struct CreateEnergyDensityOperation
     typedef FieldTmpOperation< ParticleEnergyDensity, T_Species > type;
 };
 
-/* Energy */
+/** Kinetic Energy Operation for Particle to Grid Projections
+ *
+ * Derives a scalar field for summed kinetic particle energy from a particle
+ * species at runtime.
+ * Each value is mapped per cell according to the species' spatial shape.
+ *
+ * @note this is the same as @see CreateEnergyDensityOperation times the cell
+ *       volume
+ *
+ * @tparam T_Species a @see picongpu::Particles class with a species definition,
+ *                   see @see speciesDefinition.param
+ *
+ * @typedef CreateEnergyOperation< T_Species >::type a field that can be used in
+ *          @see fileOutput.param @see picongpu::FileOutputFields
+ */
 template<typename T_Species>
 struct CreateEnergyOperation
 {
@@ -169,7 +274,22 @@ struct CreateEnergyOperation
     typedef FieldTmpOperation< ParticleEnergy, T_Species > type;
 };
 
-/* Ratio between a selected momentum component and total momentum */
+/** Momentum Ratio Operation for Particle to Grid Projections
+ *
+ * Derives a scalar field with ratio between a selected momentum component and
+ * total momentum from a particle species at runtime. Results are in the range
+ * [ -1. : 1. ], resting particles are set to 0.
+ * Each value is mapped per cell according to the species' spatial shape.
+ *
+ * @tparam T_Species a @see picongpu::Particles class with a species definition,
+ *                   see @see speciesDefinition.param
+ * @tparam T_Direction a @see boost::mpl::int_< int > variable with int as:
+ *                     0=X (default), 1=Y or 2=Z, example: bmpl::int_<1>
+ *
+ * @typedef CreateMomentumComponentOperation< T_Species, T_Direction >::type a
+ *          field that can be used in @see fileOutput.param
+ *          @see picongpu::FileOutputFields
+ */
 template<typename T_Species, typename T_Direction = bmpl::int_<0> >
 struct CreateMomentumComponentOperation
 {
@@ -183,6 +303,18 @@ struct CreateMomentumComponentOperation
 };
 
 #if(ENABLE_RADIATION == 1)
+/** Radiated Larmor Power Operation for Particle to Grid Projections
+ *
+ * Derives a scalar field with the radiated power according to the Larmor
+ * formula from a particle species at runtime.
+ * Each value is mapped per cell according to the species' spatial shape.
+ *
+ * @tparam T_Species a @see picongpu::Particles class with a species definition,
+ *                   see @see speciesDefinition.param
+ *
+ * @typedef CreateLarmorPowerOperation< T_Species >::type a field that can
+ *          be used in @see fileOutput.param @see picongpu::FileOutputFields
+ */
 template<typename T_Species>
 struct CreateLarmorPowerOperation
 {
@@ -195,7 +327,5 @@ struct CreateLarmorPowerOperation
     typedef FieldTmpOperation< ParticleLarmorPower, T_Species > type;
 };
 #endif
-
-
-} // namespace particleToGrid
-} // namespace picongpu
+} /* namespace particleToGrid */
+} /* namespace picongpu */

src/picongpu/include/simulation_defines/param/fileOutput.param

@@ -47,7 +47,7 @@ namespace picongpu
      *       note: for species that do not change their charge state, this is
      *             the same as the density times a constant for the charge
      *   - CreateEnergyOperation: sum of kinetic particle energy per cell with
-     *                            respect to shape (deprecated)
+     *                            respect to shape
      *   - CreateEnergyDensityOperation: average kinetic particle energy per
      *                                   cell times the particle density
      *       note: this is the same as the sum of kinetic particle energy