Binning
This binning plugin is a flexible binner for particles properties. Users can
Define their own axes
Define their own quantity which is binned
Choose which species which are used for the binning
Choose how frequently they want the binning to be executed
Choose if the binning should be time averaging or normalized by bin volume
Write custom output to file, for example other quantites related to the simulation which the user is interested in
Execute multiple binnings at the same time
User Input
Users can set up their binning in the binningSetup.param file. After setup, PIConGPU needs to be recompiled.
Attention
Unlike other plugins, the binning plugin doesn’t provide any runtime configuration. To set up binning, users need to define it in the param file and then recompile.
A binner is created using the addBinner() function, which describes the configuration options available to the user to set up the binning.
Multiple binnings can be run at the same time by simply calling addBinner() multiple times with different parameters.
Warning
doxygenclass: Cannot find class “picongpu::plugins::binning::BinningCreator” in doxygen xml output for project “PIConGPU” from directory: ../xml
A most important parts of defining a binning are the axes (the axes of the histogram which define the bins) and the deposited quantity (the quantity to be binned). Both of these are described using the “Functor Description”.
Functor Description
The basic building block for the binning plugin is the Functor Description object, and it is used to describe both axes and the deposited quantity. It describes the particle properties which we find interesting and how we can calculate/get this property from the particle. A functor description is created using createFunctorDescription.
-
template<typename QuantityType, typename FunctorType>
inline auto picongpu::plugins::binning::createFunctorDescription(FunctorType functor, std::string name, std::array<double, numUnits> units = std::array<double, numUnits>({0., 0., 0., 0., 0., 0., 0.})) Describes the functors, units and names for the axes and the deposited quantity.
- Todo:
infer T_Quantity from T_Functor, needs particle type also, different particles may have different return types
- Template Parameters:
QuantityType – The type returned by the functor
FunctorType – Automatically deduced type of the functor
- Parameters:
functor – Functor which access the particle property
name – Name for the functor/axis written out with the openPMD output.
units – The dimensionality of the quantity returned by the functor in the 7D format. Defaults to unitless.
- Returns:
FunctorDescription object
Functor
The functor needs to follow the signature shown below. This provides the user access to the particle object and with information about the domain.
auto myFunctor = [] ALPAKA_FN_ACC(auto const& domainInfo, auto const& worker, auto const& particle) -> returnType
{
// fn body
return myParameter;
};
The return type is defined by the user.
Domain Info
Enables the user to find the location of the particle (in cells) in the simulation domain. Contains
-
class DomainInfo
Provides knowledge of the simulation domain to the user Names and concept are described at https://github.com/ComputationalRadiationPhysics/picongpu/wiki/PIConGPU-domain-definitions.
Public Functions
Public Members
-
uint32_t currentStep
Current simulation timestep.
-
uint32_t currentStep
The global and local offsets can be understood by lookng at the PIConGPU domain definitions.
Dimensionality and units
Users can specify the units of their functor output using a 7 dimensional array. Each element of the array corresponds an SI base unit, and the value stored in that index is the exponent of the unit.
The dimensional base quantities are defined as in SIBaseUnits_t following the international system of quantities (ISQ).
If no units are given, the quantity is assumed to be dimensionless.
std::array<double, numUnits> momentumDimension{};
momentumDimension[SIBaseUnits::length] = 1.0;
momentumDimension[SIBaseUnits::mass] = 1.0;
momentumDimension[SIBaseUnits::time] = -1.0;
Warning
doxygenenum: Cannot find enum “picongpu::traits::SIBaseUnits::SIBaseUnits_t” in doxygen xml output for project “PIConGPU” from directory: ../xml
Axis
Axis is a combination of a functor description and an axis splitting These are brought together by createAxis functions, depending on what kind of an axis you want. The name used in the functor description is used as the name of the axis for openPMD.
Attention
The return type of the functor as specified in the functor description is required to be the same as the type of the range (min, max).
- Currently implemented axis types
Linear Axis
-
template<typename T_Attribute, typename T_AttrFunctor>
class LinearAxis Linear axis with contiguous fixed sized bins.
Axis splitting is defined with min, max and n_bins. Bin size = (max-min)/n_bins. Bins are closed open [) intervals [min, min + size), [min + size, min + 2*size) ,…, [max-size, max). Allocates 2 extra bins, for under and overflow. These are bin index 0 and (n_bins+2)-1 T_Attribute is a Numeric/Arithmetic type
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. In the future this plugin will support other ways to split the domain, eg. using the binWidth or by auto-selecting the parameters.
-
template<typename T_Data>
class AxisSplitting Holds the axis range in SI units and information on how this range is split into bins.
Range
-
template<typename T_Data>
class Range Holds the range in SI Units in axis space over which the binning will be done.
Species
PIConGPU species which should be used in binning. Species can be instances of a species type or a particle species name as a PMACC_CSTRING. For example,
auto electronsObj = PMACC_CSTRING("e"){};
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.
Deposited Quantity
Quantity to be deposited is simply a functor description.
Notify period
Set the periodicity of the output. Follows the period syntax defined here.
Dump Period
Defines the number of notify steps to accumulate over. Note that this is not accumulating over actual PIC iterations, but over the notify periods. If time averaging is enabled, this is also the period to do time averaging over. For example a value of 10 means that after every 10 notifies, an accumulated file will be written out. If PIConGPU exits before executing 10 notifies, then there will be no output. The plugin dumps on every notify if this is set to either 0 or 1.
Time Averaging
When dumping the accumulated output, whether or not to divide by the dump period, i.e. do a time averaging.
Attention
The user needs to set a dump period to enable time averaging.
Normalize by Bin Volume
Since it is possible to have non-uniformly sized axes, it makes sense to normalize the binned quantity by the bin volume to enable a fair comparison between bins.
Binning Particles Leaving the Simulation Volume
Warning
doxygenenum: Cannot find enum “picongpu::plugins::binning::ParticleRegion” in doxygen xml output for project “PIConGPU” from directory: ../xml
By default, only particles within the simulation volume are binned. However, users can modify this behavior to include or exclusively bin particles that are leaving the global simulation volume.
This can be configured using the enableRegion and disableRegion options with the regions defined by the ParticleRegion enum.
Users must carefully configure the notify period when using the binning plugin for leaving particles. The plugin bins particles leaving the global simulation volume at every timestep (except 0) after particles are pushed, regardless of the notify period. If the plugin is not notified at every timestep, this can cause discrepancies between the binning process and time-averaged data or histogram dumps, which follow the notify period. Additionally, the binning plugin is first notified at timestep 0, allowing users to bin initial conditions. However, leaving particles are first binned at timestep 1, after the initial particle push. Therefore, users should consider setting the notify period’s start at timestep 1, depending on their specific needs.
writeOpenPMDFunctor
Users can also write out custom output to file, for example other quantites related to the simulation which the user is interested in. This is a lambda with the following signature.
[=](::openPMD::Series& series, ::openPMD::Iteration& iteration, ::openPMD::Mesh& mesh) -> void
Note
Make sure to capture by copy only, as the objects defined in the param file are not kept alive
OpenPMD Output
The binning outputs are stored in HDF5 files in simOutput/binningOpenPMD/ directory.
The files are named as <binnerOutputName>_<timestep>.h5.
The OpenPMD mesh is call “Binning”.
The outputs in written in SI units.
If normalization is enabled, the output is normalized by the bin volume.
The output histogram has 2 bins more in each dimension than the user-defined nBins in that dimension, to deal with under and overflow.
The number of bin edges written out for an axis is one more than the user-defined nBins. These represent the bins in [min,max]. Since there are actually nBins + 2 bins, two edges are not written out.
These are the first and last edge, corresponding to the overflow bins, and they have the value of -inf and + inf.
Attribute |
Description |
|---|---|
|
Scaling factor for the deposited quantity to convert to SI |
|
The edges of the bins of an axis in SI units |
|
The units of an axis |