Particles

Particles are defined in modular steps. First, species need to be generally defined in speciesDefinition.param. Second, species are initialized with particles in speciesInitialization.param.

The following operations can be applied in the picongpu::particles::InitPipeline of the latter:

Initialization

CreateDensity

template <typename T_DensityFunctor, typename T_PositionFunctor, typename T_SpeciesType = bmpl::_1>
struct picongpu::particlesCreateDensity

Create particle distribution from a normalized density profile.

Create particles inside a species. The created particles are macroscopically distributed according to a given normalized density profile (T_DensityFunctor). Their microscopic position inside individual cells is determined by the T_PositionFunctor.

Note
FillAllGaps is automatically called after creation.
Template Parameters
  • T_DensityFunctor: unary lambda functor with profile description, see density.param, example: picongpu::particles::densityProfiles::Homogenous
  • T_PositionFunctor: unary lambda functor with position description, see particle.param, examples: picongpu::particles::startPosition::Quiet, picongpu::particles::startPosition::Random
  • T_SpeciesType: type or name as boost::mpl::string of the used species, see speciesDefinition.param

Derive

template <typename T_SrcSpeciesType, typename T_DestSpeciesType = bmpl::_1, typename T_Filter = filter::All>
struct picongpu::particlesDerive : public picongpu::particles::ManipulateDerive<manipulators::generic::None, T_SrcSpeciesType, T_DestSpeciesType, T_Filter>

Generate particles in a species by deriving from another species’ particles.

Create particles in T_DestSpeciesType by deriving (copying) all particles and their matching attributes (except particleId) from T_SrcSpeciesType.

Note
FillAllGaps is called on on T_DestSpeciesType after the derivation is finished.
Template Parameters
  • T_SrcSpeciesType: type or name as boost::mpl::string of the source species
  • T_DestSpeciesType: type or name as boost::mpl::string of the destination species
  • T_Filter: picongpu::particles::filter, particle filter type to select source particles to derive

Manipulate

template <typename T_Manipulator, typename T_SpeciesType = bmpl::_1, typename T_Filter = filter::All>
struct picongpu::particlesManipulate

Run a user defined manipulation for each particle of a species.

Allows to manipulate attributes of existing particles in a species with arbitrary unary functors (“manipulators”).

Warning
Does NOT call FillAllGaps after manipulation! If the manipulation deactivates particles or creates “gaps” in any other way, FillAllGaps needs to be called for the T_SpeciesType manually in the next step!
See
picongpu::particles::manipulators
Template Parameters
  • T_Manipulator: unary lambda functor accepting one particle species,
Template Parameters
  • T_SpeciesType: type or name as boost::mpl::string of the used species
  • T_Filter: picongpu::particles::filter, particle filter type to select particles in T_SpeciesType to manipulate via T_DestSpeciesType

ManipulateDerive

template <typename T_Manipulator, typename T_SrcSpeciesType, typename T_DestSpeciesType = bmpl::_1, typename T_SrcFilter = filter::All>
struct picongpu::particlesManipulateDerive

Generate particles in a species by deriving and manipulating from another species’ particles.

Create particles in T_DestSpeciesType by deriving (copying) all particles and their matching attributes (except particleId) from T_SrcSpeciesType. During the derivation, the particle attributes in can be manipulated with T_ManipulateFunctor.

Note
FillAllGaps is called on on T_DestSpeciesType after the derivation is finished. If the derivation also manipulates the T_SrcSpeciesType, e.g. in order to deactivate some particles for a move, FillAllGaps needs to be called for the T_SrcSpeciesType manually in the next step!
See
picongpu::particles::manipulators
Template Parameters
  • T_Manipulator: a pseudo-binary functor accepting two particle species: destination and source,
Template Parameters
  • T_SrcSpeciesType: type or name as boost::mpl::string of the source species
  • T_DestSpeciesType: type or name as boost::mpl::string of the destination species
  • T_SrcFilter: picongpu::particles::filter, particle filter type to select particles in T_SrcSpeciesType to derive into T_DestSpeciesType

FillAllGaps

template <typename T_SpeciesType = bmpl::_1>
struct picongpu::particlesFillAllGaps

Generate a valid, contiguous list of particle frames.

Some operations, such as deactivating or adding particles to a particle species can generate “gaps” in our internal particle storage, a list of frames.

This operation copies all particles from the end of the frame list to “gaps” in the beginning of the frame list. After execution, the requirement that all particle frames must be filled contiguously with valid particles and that all frames but the last are full is fulfilled.

Template Parameters
  • T_SpeciesType: type or name as boost::mpl::string of the particle species to fill gaps in memory

Manipulation Functors

Some of the particle operations above can take the following functors as arguments to manipulate attributes of particle species. A particle filter (see following section) is used to only manipulated selected particles of a species with a functor.

Free

template <typename T_Functor>
struct picongpu::particles::manipulators::genericFree : protected picongpu::particles::functor::User<T_Functor>

call simple free user defined manipulators

example for

particle.param: set in cell position to zero
struct FunctorInCellPositionZero
{
    template< typename T_Particle >
    HDINLINE void operator()( T_Particle & particle )
    {
        particle[ position_ ] = floatD_X::create( 0.0 );
    }
    static constexpr char const * name = "inCellPositionZero";
};

using InCellPositionZero = generic::Free<
   FunctorInCellPositionZero
>;
Template Parameters
  • T_Functor: user defined manipulators optional: can implement one host side constructor T_Functor() or T_Functor(uint32_t currentTimeStep)

FreeRng

template <typename T_Functor, typename T_Distribution>
struct picongpu::particles::manipulators::genericFreeRng : protected picongpu::particles::functor::User<T_Functor>, picongpu::particles::functor::misc::Rng<T_Distribution>

call simple free user defined functor and provide a random number generator

example for

particle.param: add
#include <pmacc/nvidia/rng/distributions/Uniform_float.hpp>

struct FunctorRandomX
{
    template< typename T_Rng, typename T_Particle >
    HDINLINE void operator()( T_Rng& rng, T_Particle& particle )
    {
        particle[ position_ ].x() = rng();
    }
    static constexpr char const * name = "randomXPos";
};

using RandomXPos = generic::FreeRng<
   FunctorRandomX,
   pmacc::random::distributions::Uniform< float_X >
>;
Template Parameters
  • T_Functor: user defined unary functor
  • T_Distribution: pmacc::random::distributions, random number distribution

and to InitPipeline in speciesInitialization.param:

Manipulate< manipulators::RandomXPos, SPECIES_NAME >

FreeTotalCellOffset

template <typename T_Functor>
struct picongpu::particles::manipulators::unaryFreeTotalCellOffset : protected picongpu::particles::functor::User<T_Functor>, picongpu::particles::functor::misc::TotalCellOffset

call simple free user defined manipulators and provide the cell information

The functor passes the cell offset of the particle relative to the total domain origin into the functor.

example for

particle.param: set a user-defined species attribute y0 (type: uint32_t) to the current total y-cell index
struct FunctorSaveYcell
{
    template< typename T_Particle >
    HDINLINE void operator()(
       DataSpace< simDim > const & particleOffsetToTotalOrigin,
       T_Particle & particle
    )
    {
        particle[ y0_ ] = particleOffsetToTotalOrigin.y();
    }
    static constexpr char const * name = "saveYcell";
};

using SaveYcell = unary::FreeTotalCellOffset<
   FunctorSaveYcell
>;
Template Parameters
  • T_Functor: user defined unary functor

CopyAttribute

using picongpu::particles::manipulators::unary::CopyAttribute = typedef generic::Free< acc::CopyAttribute< T_DestAttribute, T_SrcAttribute > >

copy a particle source attribute to a destination attribute

This is an unary functor and operates on one particle.

Template Parameters
  • T_DestAttribute: type of the destination attribute e.g. momentumPrev1
  • T_SrcAttribute: type of the source attribute e.g. momentum

Drift

using picongpu::particles::manipulators::unary::Drift = typedef generic::Free< acc::Drift< T_ParamClass, T_ValueFunctor > >

change particle’s momentum based on speed

allow to manipulate a speed to a particle

Template Parameters
  • T_ParamClass: param::DriftCfg, configuration parameter
  • T_ValueFunctor: pmacc::nvidia::functors::*, binary functor type to manipulate the momentum attribute

RandomPosition

using picongpu::particles::manipulators::unary::RandomPosition = typedef generic::FreeRng< acc::RandomPosition, pmacc::random::distributions::Uniform< float_X > >

Change the in cell position.

This functor changes the in-cell position of a particle. The new in-cell position is uniformly distributed position between [0.0;1.0).

example: add

particles::Manipulate<RandomPosition,SPECIES_NAME>
to InitPipeline in speciesInitialization.param

Temperature

using picongpu::particles::manipulators::unary::Temperature = typedef generic::FreeRng< acc::Temperature< T_ParamClass, T_ValueFunctor >, pmacc::random::distributions::Normal< float_X > >

change particle’s momentum based on a temperature

allow to change the temperature (randomly normal distributed) of a particle.

Template Parameters
  • T_ParamClass: param::TemperatureCfg, configuration parameter
  • T_ValueFunctor: pmacc::nvidia::functors::*, binary functor type to manipulate the momentum attribute

Assign

using picongpu::particles::manipulators::binary::Assign = typedef generic::Free< acc::Assign >

assign attributes of one particle to another

Can be used as binary and higher order operator but only the first two particles are used for the assign operation.

Assign all matching attributes of a source particle to the destination particle. Attributes that only exist in the destination species are initialized with the default value. Attributes that only exists in the source particle will be ignored.

DensityWeighting

using picongpu::particles::manipulators::binary::DensityWeighting = typedef generic::Free< acc::DensityWeighting >

Re-scale the weighting of a cloned species by densityRatio.

When deriving species from each other, the new species “inherits” the macro-particle weighting of the first one. This functor can be used to manipulate the weighting of the new species’ macro particles to satisfy the input densityRatio of it.

note: needs the densityRatio flag on both species, used by the GetDensityRatio trait.

ProtonTimesWeighting

using picongpu::particles::manipulators::binary::ProtonTimesWeighting = typedef generic::Free< acc::ProtonTimesWeighting >

Re-scale the weighting of a cloned species by numberOfProtons.

When deriving species from each other, the new species “inherits” the macro-particle weighting of the first one. This functor can be used to manipulate the weighting of the new species’ macro particles to be a multiplied by the number of protons of the initial species.

As an example, this is useful when initializing a quasi-neutral, pre-ionized plasma of ions and electrons. Electrons can be created from ions via deriving and increasing their weight to avoid simulating multiple macro electrons per macro ion (with Z>1).

note: needs the atomicNumbers flag on the initial species, used by the GetAtomicNumbers trait.

Manipulation Filters

Most of the particle functors shall operate on all valid particles, where filter::All is the default assumption. One can limit the domain or subset of particles with filters such as the ones below (or define new ones).

All

struct picongpu::particles::filterAll

RelativeGlobalDomainPosition

template <typename T_Params>
struct picongpu::particles::filterRelativeGlobalDomainPosition

filter particle dependent on the global position

Check if a particle is within a relative area in one direction of the global domain.

Template Parameters
  • T_Params: picongpu::particles::filter::param::RelativeGlobalDomainPosition, parameter to configure the functor

Free

template <typename T_Functor>
struct picongpu::particles::filter::genericFree : protected picongpu::particles::functor::User<T_Functor>

call simple free user defined filter

example for

particleFilters.param: each particle with in-cell position greater than 0.5
struct FunctorEachParticleAboveMiddleOfTheCell
{
    template< typename T_Particle >
    HDINLINE bool operator()( T_Particle const & particle )
    {
        bool result = false;
        if( particle[ position_ ] >= float_X( 0.5 ) )
            result = true;
        return result;
    }
};

using EachParticleAboveMiddleOfTheCell = generic::Free<
   FunctorEachParticleAboveMiddleOfTheCell
>;
Template Parameters
  • T_Functor: user defined filter optional: can implement one host side constructor T_Functor() or T_Functor(uint32_t currentTimeStep)

FreeRng

template <typename T_Functor, typename T_Distribution>
struct picongpu::particles::filter::genericFreeRng : protected picongpu::particles::functor::User<T_Functor>, picongpu::particles::functor::misc::Rng<T_Distribution>

call simple free user defined functor and provide a random number generator

example for

particleFilters.param: get every second particle (random sample of 50%)
struct FunctorEachSecondParticle
{
    template< typename T_Rng, typename T_Particle >
    HDINLINE bool operator()(
        T_Rng & rng,
        T_Particle const & particle
    )
    {
        bool result = false;
        if( rng() >= float_X( 0.5 ) )
            result = true;
        return result;
    }
};

using EachSecondParticle = generic::FreeRng<
   FunctorEachSecondParticle,
   pmacc::random::distributions::Uniform< float_X >
>;
Template Parameters
  • T_Functor: user defined unary functor
  • T_Distribution: pmacc::random::distributions, random number distribution

FreeTotalCellOffset

template <typename T_Functor>
struct picongpu::particles::filter::genericFreeTotalCellOffset : protected picongpu::particles::functor::User<T_Functor>, picongpu::particles::functor::misc::TotalCellOffset

call simple free user defined functor and provide the cell information

The functor passes the cell offset of the particle relative to the total domain origin into the functor.

example for

particleFilters.param: each particle with a cell offset of 5 in X direction
struct FunctorEachParticleInXCell5
{
    template< typename T_Particle >
    HDINLINE bool operator()(
        DataSpace< simDim > const & particleOffsetToTotalOrigin,
        T_Particle const & particle
    )
    {
        bool result = false;
        if( particleOffsetToTotalOrigin.x() == 5 )
            result = true;
        return result;
    }
};

using EachParticleInXCell5 = generic::FreeTotalCellOffset<
   FunctorEachParticleInXCell5
>;
Template Parameters
  • T_Functor: user defined unary functor