Merge pull request #5262 from ikbuibui/binning_doc_update

Update binning plugin documentation for filtered species and log axis

docs/Doxyfile

@@ -42,3 +42,82 @@ EXTENSION_MAPPING      = .cu=C++       \
                          .param=C++    \
                          .unitless=C++ \
                          .loader=C++
+
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all
+# C-preprocessor directives found in the sources and include files.
+# The default value is: YES.
+
+ENABLE_PREPROCESSING   = YES
+
+# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
+# in the source code. If set to NO, only conditional compilation will be
+# performed. Macro expansion can be done in a controlled way by setting
+# EXPAND_ONLY_PREDEF to YES.
+# The default value is: NO.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+MACRO_EXPANSION        = YES
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
+# the macro expansion is limited to the macros specified with the PREDEFINED and
+# EXPAND_AS_DEFINED tags.
+# The default value is: NO.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+EXPAND_ONLY_PREDEF     = NO
+
+# If the SEARCH_INCLUDES tag is set to YES, the include files in the
+# INCLUDE_PATH will be searched if a #include is found.
+# The default value is: YES.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+SEARCH_INCLUDES        = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by the
+# preprocessor.
+# This tag requires that the tag SEARCH_INCLUDES is set to YES.
+
+INCLUDE_PATH           =
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
+# patterns (like *.h and *.hpp) to filter out the header-files in the
+# directories. If left blank, the patterns specified with FILE_PATTERNS will be
+# used.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+INCLUDE_FILE_PATTERNS  =
+
+# The PREDEFINED tag can be used to specify one or more macro names that are
+# defined before the preprocessor is started (similar to the -D option of e.g.
+# gcc). The argument of the tag is a list of macros of the form: name or
+# name=definition (no spaces). If the definition and the "=" are omitted, "=1"
+# is assumed. To prevent a macro definition from being undefined via #undef or
+# recursively expanded use the := operator instead of the = operator.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+PREDEFINED             = ENABLE_OPENPMD
+
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
+# tag can be used to specify a list of macro names that should be expanded. The
+# macro definition that is found in the sources will be used. Use the PREDEFINED
+# tag if you want to use a different macro definition that overrules the
+# definition found in the source code.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+EXPAND_AS_DEFINED      =
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
+# remove all references to function-like macros that are alone on a line, have
+# an all uppercase name, and do not end with a semicolon. Such function macros
+# are typically used for boiler-plate code, and will confuse the parser if not
+# removed.
+# The default value is: YES.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+SKIP_FUNCTION_MACROS   = YES

docs/source/usage/plugins/binningPlugin.rst

@@ -78,7 +78,7 @@ If no units are given, the quantity is assumed to be dimensionless.
     momentumDimension[SIBaseUnits::mass] = 1.0;
     momentumDimension[SIBaseUnits::time] = -1.0;
 
-.. doxygenenum:: picongpu::traits::SIBaseUnits::SIBaseUnits_t
+.. doxygenenum:: picongpu::SIBaseUnits::SIBaseUnits_t
 
 
 Axis
@@ -93,18 +93,24 @@ The name used in the functor description is used as the name of the axis for ope
 
 Currently implemented axis types
     - Linear Axis
+    - Log Axis
 
 .. doxygenclass:: picongpu::plugins::binning::axis::LinearAxis
 
 .. - Equally spaced bins between min and max. Total number of bins equal to n_bins.
 ..            axis::createLinear(cellY_splitting, cellPositionYDescription);
 
+.. doxygenclass:: picongpu::plugins::binning::axis::LogAxis
+
+.. - Logarithmically spaced bins between min and max. Total number of bins equal to n_bins.
+..            axis::createLog(cellY_splitting, cellPositionYDescription);
+
 
 Binning can be done over an arbitrary number of axes, by creating a tuple of all the axes. Limited by memory depending on number of bins in each axis.
 
 Axis Splitting
 ^^^^^^^^^^^^^^
-Defines the axis range and how it is split into bins.
+Defines the axis range and how it is split into bins. Bins are defined as closed open intervals from the lower edge to the upper edge.
 In the future, this plugin will support other ways to split the domain, eg. using the binWidth or by auto-selecting the parameters.
 
 .. doxygenclass:: picongpu::plugins::binning::axis::AxisSplitting
@@ -117,6 +123,11 @@ Range
 .. doxygenclass:: picongpu::plugins::binning::axis::Range
     :members:
 
+.. note::
+
+   Axes are passed to addBinner grouped in a tuple. This is just a collection of axis objects and is of arbitrary size. 
+   Users can make a tuple for axes by using the ``createTuple()`` function and passing in the axis objects as arguments.
+
 Species
 -------
 PIConGPU species which should be used in binning.
@@ -126,10 +137,24 @@ 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. 
+
+.. code-block:: c++
+
+    auto myFilter = [] ALPAKA_FN_ACC(auto const& domainInfo, auto const& worker, auto const& particle) -> bool
+    {
+        bool binningEnabled = true;
+        // fn body
+        return binningEnabled;
+    };
+
+    auto fitleredElectrons = FilteredSpecies{electronsObj, myFilter};
+
 .. note::
 
-   Some parameters (axes and species) are given in the form of tuples. These are just a collection of objects and are of arbitrary size.
-   Users can make a tuple by using the ``createTuple()`` function and passing in the objects as arguments.
+   Species are passed to addBinner in the form of a tuple. This is just a collection of Species and FilteredSpecies objects (the tuple can be a mixure of both) and is of arbitrary size.
+   Users can make a species tuple by using the ``createSpeciesTuple()`` function and passing in the objects as arguments.
 
 
 Deposited Quantity

include/picongpu/plugins/binning/BinningCreator.hpp

@@ -25,7 +25,9 @@
 #    include "picongpu/plugins/binning/Binner.hpp"
 #    include "picongpu/plugins/binning/BinningData.hpp"
 
+#    include <functional>
 #    include <memory>
+#    include <vector>
 
 #    include <openPMD/Series.hpp>
 
@@ -56,10 +58,6 @@ namespace picongpu
              * @param axisTupleObject tuple holding the axes
              * @param speciesTupleObject tuple holding the species to do the binning with
              * @param depositionData functorDescription of the deposited quantity
-             * @param notifyPeriod The periodicity of the output
-             * @param dumpPeriod The number of notify steps to accumulate over. Dump at the end. Defaults to 1.
-             * @param timeAveraging Time average the accumulated data when doing the dump. Defaults to true.
-             * @param normalizeByBinVolume defaults to true
              * @param writeOpenPMDFunctor Functor to write out user specified openPMD data
              */
             template<typename TAxisTuple, typename TSpeciesTuple, typename TDepositionData>