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.

class BinningCreator

An object of this class is provided to the user to add their binning setups.

Public Functions

template<typename TAxisTuple, typename TSpeciesTuple, typename TDepositionData>
inline auto addBinner(std::string binnerOutputName, TAxisTuple axisTupleObject, TSpeciesTuple speciesTupleObject, TDepositionData depositionData, std::function<void(::openPMD::Series &series, ::openPMD::Iteration &iteration, ::openPMD::Mesh &mesh)> writeOpenPMDFunctor = [](::openPMD::Series &series, ::openPMD::Iteration &iteration, ::openPMD::Mesh &mesh) {}) -> BinningData<TAxisTuple, TSpeciesTuple, TDepositionData>&

Creates a binner from user input and adds it to the vector of all binners.

Parameters:

  • binnerOutputName – filename for openPMD output. It must be unique or will cause overwrites during data dumps and undefined behaviour during restarts

  • axisTupleObject – tuple holding the axes

  • speciesTupleObject – tuple holding the species to do the binning with

  • depositionData – functorDescription of the deposited quantity

  • notifyPeriod – The periodicity of the output

  • dumpPeriod – The number of notify steps to accumulate over. Dump at the end. Defaults to 1.

  • timeAveraging – Time average the accumulated data when doing the dump. Defaults to true.

  • normalizeByBinVolume – defaults to true

  • writeOpenPMDFunctor – Functor to write out user specified openPMD data

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>
HINLINE auto picongpu::plugins::binning::createFunctorDescription(FunctorType functor, std::string name, std::array<double, 7> units = std::array<double, 7>({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.

Public Functions

inline DINLINE DomainInfo(uint32_t simStep, pmacc::DataSpace<SIMDIM> gOffset, pmacc::DataSpace<SIMDIM> lOffset, DataSpace<SIMDIM> physicalSuperCellIdx)
Parameters:

physicalSuperCellIdx – supercell index relative to the border origin

Public Members

uint32_t currentStep

Current simulation timestep.

pmacc::DataSpace<SIMDIM> globalOffset

Offset of the global domain on all GPUs.

pmacc::DataSpace<SIMDIM> localOffset

Offset of the domain simulated on current GPU.

pmacc::DataSpace<SIMDIM> blockCellOffset

Offset of domain simulated by current block wrt the border.

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, 7> momentumDimension{};
momentumDimension[SIBaseUnits::length] = 1.0;
momentumDimension[SIBaseUnits::mass] = 1.0;
momentumDimension[SIBaseUnits::time] = -1.0;
enum picongpu::traits::SIBaseUnits::SIBaseUnits_t

Values:

enumerator length
enumerator mass
enumerator time
enumerator electricCurrent
enumerator thermodynamicTemperature
enumerator amountOfSubstance
enumerator luminousIntensity

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

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.

Public Members

Range<T_Data> m_range

Range object in SI units.

uint32_t nBins

Number of bins in range.

const bool enableOverflowBins

Enable or Disable overflow bins.

Number of overflow bis is the responsibility of the axis implementaiton Defaults to true

Range
template<typename T_Data>
class Range

Holds the range in SI Units in axis space over which the binning will be done.

Public Members

T_Data min

Minimum of binning range in SI Units.

T_Data max

Maximum of binning range in SI Units.

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.

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

unitSI

Scaling factor for the deposited quantity to convert to SI

<axisName>_bin_edges

The edges of the bins of an axis in SI units

<axisName>_units

The units of an axis