Merge pull request ComputationalRadiationPhysics#5402 from ikbuibui/fields_fix

Field binning fixes to pass fields and setters to configure binning

Author: psychocoderHPC

docs/source/usage/plugins/binningPlugin.rst

@@ -191,7 +191,7 @@ Species can be instances of a species type or a particle species name as a PMACC
 	auto electronsObj = PMACC_CSTRING("e"){};
 
 Optionally, users can specify a filter to be used with the species. This is a predicate functor, i.e. it is a functor with a signature as described above and which returns a boolean. If the filter returns true it means the particle is included in the binning.
-They can then create a FilteredSpecies object which contains the species and the filter.
+They can then create a ``FilteredSpecies`` object which contains the species and the filter.
 
 .. literalinclude:: ../../../../share/picongpu/tests/compile2/include/picongpu/param/binningSetup.param
    :language: c++
@@ -207,21 +207,37 @@ They can then create a FilteredSpecies object which contains the species and the
 Fields
 ------
 PIConGPU fields which should be used in field binning.
-Fields can be instances of a field type. For example,
+Fields must be instances of the ``FieldInfo`` type.
+
+.. doxygenclass:: picongpu::plugins::binning::FieldInfo
+	:members:
+
+For example,
 
 .. literalinclude:: ../../../../share/picongpu/tests/compile2/include/picongpu/param/binningSetup.param
    :language: c++
    :start-after: doc-include-start: fieldTuple
    :end-before: doc-include-end: fieldTuple
    :dedent:
 
-Fields are passed to addFieldBinner in the form of a tuple. This is just a collection of field objects and is of arbitrary size.
+Fields are passed to addFieldBinner in the form of a tuple. This is just a collection of ``FieldInfo`` and is of arbitrary size.
 Users can make a fields tuple by using the ``createTuple()`` function and passing in the objects as arguments.
+The functors receive the fields in the form of the field data box, which is the field data on the current GPU including the guard cells, in the order they are passed in the tuple.
+
+.. literalinclude:: ../../../../share/picongpu/tests/compile2/include/picongpu/param/binningSetup.param
+   :language: c++
+   :start-after: doc-include-start: fieldBox
+   :end-before: doc-include-end: fieldBox
+   :dedent:
 
 .. note::
 
 	It is possible to have an empty tuple for fields when doing field binning, in which case the functor will be called with no fields. This may be useful if you are passing in extra data and want field traversal over it.
 
+.. note::
+
+    It is possible to have field information available while doing particle binning as well. Users can simply pass in ``FieldInfo`` objects in the extra data tuple, and the functor will be called with the field information as well.
+
 Deposited Quantity
 ------------------
 Quantity to be deposited is simply a :ref:`functor description <usage/plugins/binningPlugin:Functor Description>`.

include/picongpu/plugins/binning/BinningCreator.hpp

@@ -110,7 +110,7 @@ namespace picongpu
              *         This can be used to further configure the binning setup if needed.
              */
             template<typename T_AccumulateOp = alpaka::AtomicAdd, typename T_Extras = std::tuple<>>
-            auto addFieldBinner(
+            auto& addFieldBinner(
                 std::string const& binnerOutputName,
                 auto const& axisTupleObject,
                 auto const& fieldsTupleObject,

include/picongpu/plugins/binning/BinningData.hpp

@@ -117,51 +117,51 @@ namespace picongpu
             /** @brief Time average the accumulated data when doing the dump. Defaults to true. */
             Child& setTimeAveraging(bool timeAv)
             {
-                this->timeAveraging = timeAv;
+                timeAveraging = timeAv;
                 return interpretAsChild();
             }
 
             /** @brief The periodicity of the output. Defaults to 1 */
             Child& setNotifyPeriod(std::string notify)
             {
-                this->notifyPeriod = std::move(notify);
+                notifyPeriod = std::move(notify);
                 return interpretAsChild();
             }
 
             /** @brief The number of notify steps to accumulate over. Dump at the end. Defaults to 1. */
             Child& setDumpPeriod(uint32_t dumpXNotifys)
             {
-                this->dumpPeriod = dumpXNotifys;
+                dumpPeriod = dumpXNotifys;
                 return interpretAsChild();
             }
 
-            /** @brief The periodicity of the output. Defaults to 1 */
+            /** @brief Set the file extension for the openPMD output */
             Child& setOpenPMDExtension(std::string extension)
             {
-                this->openPMDExtension = std::move(extension);
+                openPMDExtension = std::move(extension);
                 return interpretAsChild();
             }
 
-            /** @brief The periodicity of the output. Defaults to 1 */
+            /** @brief Set the infix for file names in openPMD output */
             Child& setOpenPMDInfix(std::string infix)
             {
-                this->openPMDInfix = std::move(infix);
+                openPMDInfix = std::move(infix);
                 return interpretAsChild();
             }
 
-            /** @brief The periodicity of the output. Defaults to 1 */
+            /** @brief Call a functor to add custom data to openPMD output */
             Child& setOpenPMDWriteFunctor(
                 std::function<void(::openPMD::Series& series, ::openPMD::Iteration& iteration, ::openPMD::Mesh& mesh)>
-                    writeOpenPMDFunctor)
+                    functor)
             {
-                this->writeOpenPMDFunctor = std::move(writeOpenPMDFunctor);
+                writeOpenPMDFunctor = std::move(functor);
                 return interpretAsChild();
             }
 
-            /** @brief The periodicity of the output. Defaults to 1 */
+            /** @brief Set miscellaneous configuration options for openPMD output */
             Child& setOpenPMDJsonCfg(std::string cfg)
             {
-                this->openPMDJsonCfg = std::move(cfg);
+                openPMDJsonCfg = std::move(cfg);
                 return interpretAsChild();
             }
 
@@ -170,7 +170,7 @@ namespace picongpu
              */
             Child& setHostSideHook(std::function<void()> hookFunc)
             {
-                this->hostHook = std::move(hookFunc);
+                hostHook = std::move(hookFunc);
                 return interpretAsChild();
             }
         };

include/picongpu/plugins/binning/BinningFunctors.hpp

@@ -105,24 +105,22 @@ namespace picongpu
                 auto const& worker,
                 T_HistBox binningBox,
                 auto particlesBox,
-                pmacc::DataSpace<simDim> const& localOffset,
-                pmacc::DataSpace<simDim> const& globalOffset,
+                DomainInfo<BinningType::Particle> domainInfo,
                 auto const& axisTuple,
                 T_DepositionFunctor const& quantityFunctor,
                 DataSpace<T_nAxes> const& extents,
                 auto const& userFunctorData,
                 auto const& filter,
-                uint32_t const currentStep,
                 T_Mapping const& mapper) const
             {
                 DataSpace<simDim> const superCellIdx(mapper.getSuperCellIndex(worker.blockDomIdxND()));
+                auto const guardingSuperCells = mapper.getGuardingSuperCells();
                 // supercell index relative to the border origin
-                auto const physicalSuperCellIdx = superCellIdx - mapper.getGuardingSuperCells();
+                auto const physicalSuperCellIdx = superCellIdx - guardingSuperCells;
                 /**
                  * Init the Domain info, here because of the possibility of a moving window
                  */
-                auto const domainInfo
-                    = DomainInfo<BinningType::Particle>{currentStep, globalOffset, localOffset, physicalSuperCellIdx};
+                domainInfo.fillDeviceData(physicalSuperCellIdx);
 
                 auto const functorParticle = FunctorParticle<T_AtomicOp>{};
 
@@ -194,25 +192,23 @@ namespace picongpu
                 T_Worker const& worker,
                 T_HistBox binningBox,
                 TParticlesBox particlesBox,
-                pmacc::DataSpace<simDim> const& localOffset,
-                pmacc::DataSpace<simDim> const& globalOffset,
+                DomainInfo<BinningType::Particle> domainInfo,
                 T_AxisTuple const& axisTuple,
                 T_DepositionFunctor const& quantityFunctor,
                 DataSpace<T_nAxes> const& extents,
                 auto const& userFunctorData,
                 auto const& filter,
-                uint32_t const currentStep,
                 pmacc::DataSpace<simDim> const& beginCellIdxLocal,
                 pmacc::DataSpace<simDim> const& endCellIdxLocal,
                 T_Mapping const& mapper) const
             {
                 /* multi-dimensional offset vector from local domain origin on GPU in units of super cells */
                 pmacc::DataSpace<simDim> const superCellIdx(mapper.getSuperCellIndex(worker.blockDomIdxND()));
+                auto const guardingSuperCells = mapper.getGuardingSuperCells();
                 // supercell index relative to the border origin
-                auto const physicalSuperCellIdx = superCellIdx - mapper.getGuardingSuperCells();
+                auto const physicalSuperCellIdx = superCellIdx - guardingSuperCells;
 
-                auto const domainInfo
-                    = DomainInfo<BinningType::Particle>{currentStep, globalOffset, localOffset, physicalSuperCellIdx};
+                domainInfo.fillDeviceData(physicalSuperCellIdx);
                 auto const functorParticle = FunctorParticle<T_AtomicOp>{};
 
                 auto forEachParticle
@@ -317,21 +313,20 @@ namespace picongpu
             DINLINE void operator()(
                 auto const& worker,
                 T_HistBox binningBox,
-                pmacc::DataSpace<simDim> const& localOffset,
-                pmacc::DataSpace<simDim> const& globalOffset,
+                DomainInfo<BinningType::Field> domainInfo,
                 auto const& axisTuple,
                 auto const& userFunctorData,
                 T_DepositionFunctor const& quantityFunctor,
                 DataSpace<T_nAxes> const& extents,
-                uint32_t const currentStep,
                 T_Mapping const& mapper) const
             {
                 using SuperCellSize = typename T_Mapping::SuperCellSize;
                 constexpr uint32_t cellsPerSupercell = pmacc::math::CT::volume<SuperCellSize>::type::value;
 
                 DataSpace<simDim> const superCellIdx(mapper.getSuperCellIndex(worker.blockDomIdxND()));
+                auto const guardingSuperCells = mapper.getGuardingSuperCells();
                 // supercell index relative to the border origin
-                auto const physicalSuperCellIdx = superCellIdx - mapper.getGuardingSuperCells();
+                auto const physicalSuperCellIdx = superCellIdx - guardingSuperCells;
 
                 using SuperCellSize = typename T_Mapping::SuperCellSize;
 
@@ -348,12 +343,7 @@ namespace picongpu
                         /**
                          * Init the Domain info, here because of the possibility of a moving window
                          */
-                        auto const domainInfo = DomainInfo<BinningType::Field>{
-                            currentStep,
-                            globalOffset,
-                            localOffset,
-                            physicalSuperCellIdx,
-                            localCellIndex};
+                        domainInfo.fillDeviceData(physicalSuperCellIdx, localCellIndex);
 
                         functorCell(
                             worker,