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
, typenameT_PositionFunctor
, typenameT_SpeciesType
= bmpl::_1>
structCreateDensity
¶ 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
, typenameT_DestSpeciesType
= bmpl::_1, typenameT_Filter
= filter::All>
structDerive
: 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
, typenameT_Species
= bmpl::_1, typenameT_Filter
= filter::All>
structManipulate
: public pmacc::particles::algorithm::CallForEach<pmacc::particles::meta::FindByNameOrType<VectorAllSpecies, T_Species>, detail::MakeUnaryFilteredFunctor<T_Manipulator, T_Species, T_Filter>>¶ 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_Species
manually in the next step!- See
picongpu::particles::manipulators
- Template Parameters
T_Manipulator
: unary lambda functor accepting one particle species,
- Template Parameters
T_Species
: type or name as boost::mpl::string of the used speciesT_Filter
: picongpu::particles::filter, particle filter type to select particles inT_Species
to manipulate
ManipulateDerive¶
-
template<typename
T_Manipulator
, typenameT_SrcSpeciesType
, typenameT_DestSpeciesType
= bmpl::_1, typenameT_SrcFilter
= filter::All>
structManipulateDerive
¶ 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>
structFillAllGaps
¶ 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
>
structFree
: 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
, typenameT_Distribution
>
structFreeRng
: protected picongpu::particles::functor::User<T_Functor>, private 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
>
structFreeTotalCellOffset
: protected picongpu::particles::functor::User<T_Functor>, private 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
= 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
= 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
= 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
= 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
= 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
= 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
= 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
>
structRelativeGlobalDomainPosition
¶ 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
>
structFree
: 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_ ].y() >= float_X( 0.5 ) ) result = true; return result; } static constexpr char const * name = "eachParticleAboveMiddleOfTheCell"; }; 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
, typenameT_Distribution
>
structFreeRng
: protected picongpu::particles::functor::User<T_Functor>, private 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; } static constexpr char const * name = "eachSecondParticle"; }; 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
>
structFreeTotalCellOffset
: protected picongpu::particles::functor::User<T_Functor>, private 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; } static constexpr char const * name = "eachParticleInXCell5"; }; using EachParticleInXCell5 = generic::FreeTotalCellOffset< FunctorEachParticleInXCell5 >;
- Template Parameters
T_Functor
: user defined unary functor