Particles

Initialization

The following operations can be applied in the picongpu::particles::InitPipeline inside speciesInitialization.param:

CreateDensity

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

create density based on a normalized profile and a position profile

constructor with current time step of density and position profile is called after the density profile is created fillAllGaps() is called

Template Parameters
  • T_DensityFunctor: unary lambda functor with profile description
  • T_PositionFunctor: unary lambda functor with position description
  • T_SpeciesType: type of the used species

DeriveSpecies

template <typename T_SrcSpeciesType, typename T_DestSpeciesType = bmpl::_1, typename T_Filter = filter::IsHandleValid>
struct picongpu::particles::DeriveSpecies

derive species out of a another species

after the species is derived fillAllGaps() on T_DestSpeciesType is called copy all attributes from the source species except particleId to the destination species

Template Parameters
  • T_SrcSpeciesType: source species
  • T_DestSpeciesType: destination species
  • T_Filter: picongpu::particles::filter, particle filter type to select particles

Inherits from picongpu::particles::ManipulateDeriveSpecies< manipulators::generic::None, T_SrcSpeciesType, T_DestSpeciesType, T_Filter >

Manipulate

template <typename T_Functor, typename T_SpeciesType = bmpl::_1, typename T_Filter = filter::IsHandleValid>
struct picongpu::particles::Manipulate

run a user defined functor for every particle

  • constructor with current time step is called for the functor on the host side
  • Warning
    fillAllGaps() is not called
    Template Parameters
    • T_Functor: unary lambda functor
    • T_SpeciesType: type of the used species
    • T_Filter: picongpu::particles::filter, particle filter type to select particles

ManipulateDeriveSpecies

template <typename T_Functor, typename T_SrcSpeciesType, typename T_DestSpeciesType = bmpl::_1, typename T_Filter = filter::IsHandleValid>
struct picongpu::particles::ManipulateDeriveSpecies

derive species out of a another species

after the species is derived fillAllGaps() on T_DestSpeciesType is called copy all attributes from the source species except particleId to the destination species

See
include/picongpu/particles/manipulators
Template Parameters
  • T_ManipulateFunctor: a pseudo-binary functor accepting two particle species: destination and source,
Template Parameters
  • T_SrcSpeciesType: source species
  • T_DestSpeciesType: destination species
  • T_Filter: picongpu::particles::filter, particle filter type to select particles

FillAllGaps

template <typename T_SpeciesType = bmpl::_1>
struct picongpu::particles::FillAllGaps

call method fill all gaps of a species

Template Parameters
  • T_SpeciesType: type of the species

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::generic::Free

call simple free user defined functor

Template Parameters
  • T_Functor: user defined functor optional: can implement one host side constructor T_Functor() or T_Functor(uint32_t currentTimeStep)

Inherits from T_Functor

FreeRng

template <typename T_Functor, typename T_Distribution, typename T_Seed, typename T_SpeciesType>
struct picongpu::particles::manipulators::generic::FreeRng

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

example: add

#include <pmacc/nvidia/rng/distributions/Uniform_float.hpp>

struct RandomXFunctor
{
    template< typename T_Rng, typename T_Particle >
    DINLINE void operator()( T_Rng& rng, T_Particle& particle )
    {
        particle[ position_ ].x() = rng();
    }
};

using RandomXPos = FreeRng<
   RandomXFunctor,
   nvidia::rng::distributions::Uniform_float
>;
particles::Manipulate< RandomXPos, SPECIES_NAME >
to InitPipeline in speciesInitialization.param
Template Parameters
  • T_Functor: user defined unary functor
  • T_Distribution: random number distribution
  • T_Seed: seed to initialize the random number generator
  • T_SpeciesType: type of the species that shall be manipulated

Inherits from T_Functor, picongpu::particles::manipulators::generic::detail::Rng< T_Distribution, T_Seed, T_SpeciesType >

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, nvidia::rng::distributions::Uniform_float, boost::mpl::integral_c< size_t, POSITION_SEED > >

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 >, nvidia::rng::distributions::Normal_float, boost::mpl::integral_c< size_t, TEMPERATURE_SEED > >

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 IsHandleValid is the default assumption. One can limit the domain or subset of particles with filters such as the ones below (or define new ones).

IsHandleValid

struct picongpu::particles::filter::IsHandleValid

RelativeGlobalDomainPosition

template <typename T_Params>
struct picongpu::particles::filter::RelativeGlobalDomainPosition

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

Define a New Particle Filter

Note

Not yet implemented.