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 theT_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::HomogenousT_PositionFunctor
: unary lambda functor with position description, see particle.param, examples: picongpu::particles::startPosition::Quiet, picongpu::particles::startPosition::RandomT_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 (exceptparticleId
) fromT_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 speciesT_DestSpeciesType
: type or name as boost::mpl::string of the destination speciesT_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 speciesT_Filter
: picongpu::particles::filter, particle filter type to select particles inT_SpeciesType
to manipulate viaT_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 (exceptparticleId
) fromT_SrcSpeciesType
. During the derivation, the particle attributes in can be manipulated withT_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 speciesT_DestSpeciesType
: type or name as boost::mpl::string of the destination speciesT_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 zerostruct 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 constructorT_Functor()
orT_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 functorT_Distribution
: pmacc::random::distributions, random number distribution
and to
InitPipeline
inspeciesInitialization.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 indexstruct 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 parameterT_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
toparticles::Manipulate<RandomPosition,SPECIES_NAME>
InitPipeline
inspeciesInitialization.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 parameterT_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).
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.5struct 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 constructorT_Functor()
orT_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 functorT_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 directionstruct 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