From 71aab9e3ec107b91a1109fdad36901b56d822e40 Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Tue, 24 Jan 2017 17:04:38 +0100 Subject: [PATCH] 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`. --- .../ComputeGridValuePerFrame.def | 162 ++++++++++++++++-- .../simulation_defines/param/fileOutput.param | 2 +- 2 files changed, 147 insertions(+), 17 deletions(-) diff --git a/src/picongpu/include/particles/particleToGrid/ComputeGridValuePerFrame.def b/src/picongpu/include/particles/particleToGrid/ComputeGridValuePerFrame.def index 6e29199a81..9b1628f947 100644 --- a/src/picongpu/include/particles/particleToGrid/ComputeGridValuePerFrame.def +++ b/src/picongpu/include/particles/particleToGrid/ComputeGridValuePerFrame.def @@ -18,7 +18,14 @@ * If not, see . */ - +/** @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 #include + namespace picongpu { namespace particleToGrid { - template 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 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 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 > 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 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 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 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 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 > 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 struct CreateLarmorPowerOperation { @@ -195,7 +327,5 @@ struct CreateLarmorPowerOperation typedef FieldTmpOperation< ParticleLarmorPower, T_Species > type; }; #endif - - -} // namespace particleToGrid -} // namespace picongpu +} /* namespace particleToGrid */ +} /* namespace picongpu */ diff --git a/src/picongpu/include/simulation_defines/param/fileOutput.param b/src/picongpu/include/simulation_defines/param/fileOutput.param index 2022bc3051..b888f9a064 100644 --- a/src/picongpu/include/simulation_defines/param/fileOutput.param +++ b/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