Important pmacc Classes

This is very, very small selection of classes of interest to get you started.

Note

Please help adding more Doxygen doc strings to the classes described below. As an example, here is a listing of possible extensive docs that new developers find are missing: https://github.com/ComputationalRadiationPhysics/picongpu/issues/776

Environment

template<uint32_t T_dim> class Environment : public pmacc::detail::Environment

Global Environment singleton for PMacc.

Public Functions

HINLINE void enableMpiDirect ()

HINLINE bool isMpiDirectEnabled () const

HINLINE pmacc::GridController< T_dim > & GridController ()

get the singleton GridController

Returns:: instance of GridController

HINLINE pmacc::SubGrid< T_dim > & SubGrid ()

get the singleton SubGrid

Returns:: instance of SubGrid

HINLINE pmacc::Filesystem< T_dim > & Filesystem ()

get the singleton Filesystem

Returns:: instance of Filesystem

HINLINE void initDevices (DataSpace< T_dim > devices, DataSpace< T_dim > periodic)

create and initialize the environment of PMacc

Usage of MPI or device(accelerator) function calls before this method are not allowed.

Parameters:

devices – number of devices per simulation dimension
periodic – periodicity each simulation dimension (0 == not periodic, 1 == periodic)

HINLINE void initGrids (DataSpace< T_dim > globalDomainSize, DataSpace< T_dim > localDomainSize, DataSpace< T_dim > localDomainOffset)

initialize the computing domain information of PMacc

Parameters:

globalDomainSize – size of the global simulation domain [cells]
localDomainSize – size of the local simulation domain [cells]
localDomainOffset – local domain offset [cells]

Environment(const Environment&) = delete

Environment &operator=(const Environment&) = delete

Public Static Functions

static inline Environment<T_dim> &get()

get the singleton Environment< DIM >

Returns:: instance of Environment<DIM >

DataConnector

class DataConnector

Singleton class which collects and shares simulation data.

All members are kept as shared pointers, which allows their factories to be destroyed after sharing ownership with our DataConnector.

Public Functions

bool hasId(SimulationDataId id)

Returns if data with identifier id is shared.

Parameters:: id – id of the Dataset to query
Returns:: if dataset with id is registered

void initialise(AbstractInitialiser &initialiser, uint32_t currentStep)

Initialises all Datasets using initialiser.

After initialising, the Datasets will be invalid.

Parameters:

initialiser – class used for initialising Datasets
currentStep – current simulation step

void share(const std::shared_ptr<ISimulationData> &data)

Register a new Dataset and share its ownership.

If a Dataset with the same id already exists, a runtime_error is thrown. (Check with DataConnector::hasId when necessary.)

Parameters:: data – simulation data to share ownership

void consume(std::unique_ptr<ISimulationData> data)

Register a new Dataset and transfer its ownership.

If a Dataset with the same id already exists, a runtime_error is thrown. (Check with DataConnector::hasId when necessary.) The only difference from share() is transfer of ownership.

Parameters:: data – simulation data to transfer ownership

void deregister(SimulationDataId id)

End sharing a dataset with identifier id.

Parameters:: id – id of the dataset to remove

void clean(): Unshare all associated datasets.

template<class TYPE> inline std::shared_ptr<TYPE> get(SimulationDataId id)

Returns shared pointer to managed data.

Reference to data in Dataset with identifier id and type TYPE is returned. Increments the reference counter to the dataset specified by id.

Template Parameters:: TYPE – if of the data to load
Parameters:: id – id of the Dataset to load from
Returns:: returns a reference to the data of type TYPE

Friends

friend struct detail::Environment

DataSpace

template<unsigned T_dim> class DataSpace : public pmacc::math::Vector<int, T_dim>

A T_dim-dimensional vector of integers.

The object is used to describe indices of threads in the kernel. DataSpace describes a T_dim-dimensional data space with a specific size for each dimension. It only describes the space and does not hold any actual data.

Attention: Currently this object is also used to describe memory extents. This should be avoided and is a technical dept from the past and limits the index space to 2 giga elements.

Template Parameters:: T_dim – dimension N of the dataspace

Public Types

using BaseType = math::Vector<int, T_dim>

Public Functions

inline HDINLINE DataSpace()

default constructor.

Sets size of all dimensions to 0.

constexpr HDINLINE DataSpace(const DataSpace&) = default

constexpr HDINLINE DataSpace & operator= (const DataSpace &)=default

template<typename T_MemberType> inline explicit HDINLINE DataSpace(alpaka::Vec<::alpaka::DimInt<T_dim>, T_MemberType> const &value)

constructor.

Sets size of all dimensions from alpaka.

template<typename ...T_Args, typename = std::enable_if_t<(std::is_convertible_v<T_Args, int> && ...)>> inline constexpr HDINLINE DataSpace(T_Args&&... args)

Constructor for N-dimensional DataSpace.

Attention: This constructor allows implicit casts.

Parameters:: args – size of each dimension, x,y,z,…

inline constexpr HDINLINE DataSpace(const BaseType &vec)

inline HDINLINE DataSpace(const math::Size_t<T_dim> &vec)

inline HDINLINE int getDim () const

Returns number of dimensions (T_dim) of this DataSpace.

Returns:: number of dimensions

inline HINLINE bool isOneDimensionGreaterThan (const MemSpace< T_dim > &other) const

Evaluates if one dimension is greater than the respective dimension of other.

Parameters:: other – DataSpace to compare with
Returns:: true if one dimension is greater, false otherwise

inline HDINLINE operator math::Size_t<T_dim>() const

Public Static Functions

static inline HDINLINE DataSpace< T_dim > create (int value=1)

Give DataSpace where all dimensions set to init value.

Parameters:: value – value which is setfor all dimensions
Returns:: the new DataSpace

Public Static Attributes

static constexpr uint32_t Dim = T_dim 

Vector

template<typename T_Type, uint32_t T_dim, typename T_Navigator = IdentityNavigator, typename T_Storage = detail::Vector_components<T_Type, T_dim>> struct Vector : private pmacc::math::detail::Vector_components<T_Type, T_dim>, protected pmacc::math::IdentityNavigator

Unnamed Group

template<uint32_t T_numElements> inline constexpr HDINLINE Vector< type, T_numElements, Navigator > shrink ()

Shrink the number of elements of a vector.

Template Parameters:: T_numElements – New dimension of the vector.
Returns:: First T_numElements elements of the origin vector

template<uint32_t T_numElements> inline HDINLINE Vector< type, T_numElements, Navigator > shrink () const

Public Types

using Storage = T_Storage 

using type = typename Storage::type

using tag = tag::Vector

using Navigator = T_Navigator 

using ParamType = typename boost::call_traits<type>::param_type

Public Functions

PMACC_CASSERT_MSG (math_Vector__with_DIM_0_is_not_allowed, dim > 0u)

constexpr Vector() = default

template<typename ...T_Args, typename = std::enable_if_t<(std::is_convertible_v<T_Args, T_Type> && ...)>> inline constexpr HDINLINE Vector(T_Args... args)

Constructor for N-dimensional vector.

Attention: This constructor allows implicit casts.

Parameters:: args – value of each dimension, x,y,z,…

constexpr HDINLINE Vector(const Vector &other) = default

template<typename T_OtherNavigator, typename T_OtherStorage> inline HDINLINE Vector(const Vector<T_Type, dim, T_OtherNavigator, T_OtherStorage> &other)

template<typename T_OtherType, typename T_OtherNavigator, typename T_OtherStorage> inline explicit HDINLINE Vector(const Vector<T_OtherType, dim, T_OtherNavigator, T_OtherStorage> &other)

template<typename T_MemberType> inline explicit HDINLINE Vector(alpaka::Vec<::alpaka::DimInt<T_dim>, T_MemberType> const &value)

Transforms an alpaka vector into the corresponding PMacc vector.

The order of members is automatically permuted from z,y,x to x,y,z.

template<uint32_t T_deferDim = T_dim, typename = typename std::enable_if<T_deferDim == 1u>::type> inline explicit HDINLINE operator type(): Allow static_cast / explicit cast to member type for 1D vector.

inline HDINLINE const Vector & toRT () const

inline HDINLINE Vector & toRT ()

inline HDINLINE Vector revert ()

HDINLINE Vector & operator= (const Vector &)=default

template<typename T_OtherNavigator, typename T_OtherStorage> inline HDINLINE Vector & operator= (const Vector< type, dim, T_OtherNavigator, T_OtherStorage > &rhs)

inline HDINLINE type & operator[] (const uint32_t idx)

inline HDINLINE const type & operator[] (const uint32_t idx) const

inline HDINLINE type & x ()

inline HDINLINE type & y ()

inline HDINLINE type & z ()

inline HDINLINE const type & x () const

inline HDINLINE const type & y () const

inline HDINLINE const type & z () const

template<uint32_t T_numElements> inline HDINLINE Vector< type, T_numElements, Navigator > shrink (const int startIdx) const

Shrink the number of elements of a vector.

Template Parameters:: T_numElements – New dimension of the vector.
Parameters:: startIdx – Index within the origin vector which will be the first element in the result.
Returns:: T_numElements elements of the origin vector starting with the index startIdx. Indexing will wrapp around when the end of the origin vector is reached.

template<uint32_t dimToRemove> inline HDINLINE Vector< type, dim - 1, Navigator > remove () const

Removes a component.

It is not allowed to call this method on a vector with the dimensionality of one.

Template Parameters:: dimToRemove – index which shall be removed; range: [ 0; dim - 1 ]
Returns:: vector with dim - 1 elements

inline HDINLINE type productOfComponents () const

Returns product of all components.

Returns:: product of components

inline HDINLINE type sumOfComponents () const

Returns sum of all components.

Returns:: sum of components

template<typename T_OtherNavigator, typename T_OtherStorage> inline HDINLINE Vector & operator+= (const Vector< type, dim, T_OtherNavigator, T_OtherStorage > &other)

+= operator

Parameters:: other – instance with same type and dimension like the left instance
Returns:: reference to manipulated left instance

template<typename T_OtherNavigator, typename T_OtherStorage> inline HDINLINE Vector & operator-= (const Vector< type, dim, T_OtherNavigator, T_OtherStorage > &other)

-= operator

Parameters:: other – instance with same type and dimension like the left instance
Returns:: reference to manipulated left instance

template<typename T_OtherNavigator, typename T_OtherStorage> inline HDINLINE Vector & operator*= (const Vector< type, dim, T_OtherNavigator, T_OtherStorage > &other)

*= operator

Parameters:: other – instance with same type and dimension like the left instance
Returns:: reference to manipulated left instance

template<typename T_OtherNavigator, typename T_OtherStorage> inline HDINLINE Vector & operator/= (const Vector< type, dim, T_OtherNavigator, T_OtherStorage > &other)

/= operator

Parameters:: other – instance with same type and dimension like the left instance
Returns:: reference to manipulated left instance

inline HDINLINE Vector & operator+= (ParamType other)

inline HDINLINE Vector & operator-= (ParamType other)

inline HDINLINE Vector & operator*= (ParamType other)

inline HDINLINE Vector & operator/= (ParamType other)

inline HDINLINE bool operator== (const Vector &rhs) const

== comparison operator.

Compares sizes of two DataSpaces.

Parameters:: other – Vector to compare to
Returns:: true if all components in both vectors are equal, else false

inline HDINLINE bool operator!= (const Vector &rhs) const

!= comparison operator.

Compares sizes of two DataSpaces.

Parameters:: other – Vector to compare to
Returns:: true if one component in both vectors are not equal, else false

inline std::string toString(const std::string separator = ",", const std::string enclosings = "{}") const

create string out of the vector

example: .toString(“;”,”|”) -> |x;…;z| .toString(“,”,”[]”) -> [x,…,z]

Parameters:

separator – string to separate components of the vector
enclosings – string with size 2 to enclose vector size == 0 ? no enclose symbols size == 1 ? means enclose symbol begin and end are equal size >= 2 ? letter[0] = begin enclose symbol letter[1] = end enclose symbol

inline HDINLINE alpaka::Vec<::alpaka::DimInt< T_dim >, MemIdxType > toAlpakaMemVec () const

Transforms a Vector into alpaka vector used for memory extent descriptions.

The order of members is automatically permuted from x,y,z to z,y,x. The member data type will be MemIdxType.

Only integral types are supported. The method is performing an static cast to MemIdxType.

inline HDINLINE alpaka::Vec<::alpaka::DimInt< T_dim >, IdxType > toAlpakaKernelVec () const

Transforms a Vector into alpaka vector used for kernel extent descriptions.

The order of members is automatically permuted from x,y,z to z,y,x. The member data type will be IdxType to fit with the accelerator index type.

Only integral types are supported. The method is performing an static cast to IdxType.

Public Static Functions

static inline HDINLINE Vector create (ParamType value)

Creates a Vector where all dimensions are set to the same value.

Parameters:: value – Value which is set for all dimensions
Returns:: new Vector<…>

Public Static Attributes

static constexpr uint32_t dim = Storage::dim

SuperCell

template<typename T_FrameType, typename T_SuperCellSize> class SuperCell

Public Types

using SuperCellSize = T_SuperCellSize 

Public Functions

inline HDINLINE SuperCell()

inline HDINLINE T_FrameType * FirstFramePtr ()

inline HDINLINE T_FrameType * LastFramePtr ()

inline HDINLINE T_FrameType * FirstFramePtr () const

inline HDINLINE T_FrameType * LastFramePtr () const

inline HDINLINE bool mustShift () const

inline HDINLINE void setMustShift (bool const value)

inline HDINLINE uint32_t getSizeLastFrame () const

inline HDINLINE uint32_t getNumParticles () const

inline HDINLINE void setNumParticles (uint32_t const size)

PMACC_ALIGN(firstFramePtr, T_FrameType*)

PMACC_ALIGN(lastFramePtr, T_FrameType*)

GridBuffer

template<class TYPE, unsigned DIM, class BORDERTYPE = TYPE> class GridBuffer : public pmacc::HostDeviceBuffer<TYPE, DIM>

GridBuffer represents a DIM-dimensional buffer which exists on the host as well as on the device.

GridBuffer combines a HostBuffer and a DeviceBuffer with equal sizes. Additionally, it allows sending data from and receiving data to these buffers. Buffers consist of core data which may be surrounded by border data.

Template Parameters:

TYPE – datatype for internal Host- and DeviceBuffer
DIM – dimension of the buffers
BORDERTYPE – optional type for border data in the buffers. TYPE is used by default.

Public Types

using DataBoxType = typename Parent::DataBoxType

Public Functions

inline GridBuffer(const GridLayout<DIM> &gridLayout, bool sizeOnDevice = false)

Constructor.

Parameters:

gridLayout – layout of the buffers, including border-cells
sizeOnDevice – if true, size information exists on device, too.

inline GridBuffer(const DataSpace<DIM> &dataSpace, bool sizeOnDevice = false)

Constructor.

Parameters:

dataSpace – DataSpace representing buffer size without border-cells
sizeOnDevice – if true, internal buffers must store their size additionally on the device (as we keep this information coherent with the host, it influences performance on host-device copies, but some algorithms on the device might need to know the size of the buffer)

inline GridBuffer(DeviceBuffer<TYPE, DIM> &otherDeviceBuffer, const GridLayout<DIM> &gridLayout, bool sizeOnDevice = false)

Constructor.

Parameters:

otherDeviceBuffer – DeviceBuffer which should be used instead of creating own DeviceBuffer
gridLayout – layout of the buffers, including border-cells
sizeOnDevice – if true, internal buffers must store their size additionally on the device (as we keep this information coherent with the host, it influences performance on host-device copies, but some algorithms on the device might need to know the size of the buffer)

inline GridBuffer(HostBuffer<TYPE, DIM> &otherHostBuffer, const DataSpace<DIM> &offsetHost, DeviceBuffer<TYPE, DIM> &otherDeviceBuffer, const DataSpace<DIM> &offsetDevice, const GridLayout<DIM> &gridLayout, bool sizeOnDevice = false)

inline void addExchange(uint32_t dataPlace, const Mask &receive, DataSpace<DIM> guardingCells, uint32_t communicationTag, bool sizeOnDeviceSend, bool sizeOnDeviceReceive)

Add Exchange in GridBuffer memory space.

An Exchange is added to this GridBuffer. The exchange buffers use the same memory as this GridBuffer.

Parameters:

dataPlace – place where received data is stored [GUARD | BORDER] if dataPlace=GUARD than copy other BORDER to my GUARD if dataPlace=BORDER than copy other GUARD to my BORDER
receive – a Mask which describes the directions for the exchange
guardingCells – number of guarding cells in each dimension
communicationTag – unique tag/id for communication has to be the same when this method is called multiple times for the same object (with non-overlapping masks)
sizeOnDeviceSend – if true, internal send buffers must store their size additionally on the device (as we keep this information coherent with the host, it influences performance on host-device copies, but some algorithms on the device might need to know the size of the buffer)
sizeOnDeviceReceive – if true, internal receive buffers must store their size additionally on the device

inline void addExchange(uint32_t dataPlace, const Mask &receive, DataSpace<DIM> guardingCells, uint32_t communicationTag, bool sizeOnDevice = false)

Add Exchange in GridBuffer memory space.

An Exchange is added to this GridBuffer. The exchange buffers use the same memory as this GridBuffer.

Parameters:

dataPlace – place where received data is stored [GUARD | BORDER] if dataPlace=GUARD than copy other BORDER to my GUARD if dataPlace=BORDER than copy other GUARD to my BORDER
receive – a Mask which describes the directions for the exchange
guardingCells – number of guarding cells in each dimension
communicationTag – unique tag/id for communication
sizeOnDevice – if true, internal buffers must store their size additionally on the device (as we keep this information coherent with the host, it influences performance on host-device copies, but some algorithms on the device might need to know the size of the buffer)

inline void addExchangeBuffer(const Mask &receive, const DataSpace<DIM> &dataSpace, uint32_t communicationTag, bool sizeOnDeviceSend, bool sizeOnDeviceReceive)

Add Exchange in dedicated memory space.

An Exchange is added to this GridBuffer. The exchange buffers use the their own memory instead of using the GridBuffer’s memory space.

Parameters:

receive – a Mask which describes the directions for the exchange
dataSpace – size of the newly created exchange buffer in each dimension
communicationTag – unique tag/id for communication
sizeOnDeviceSend – if true, internal send buffers must store their size additionally on the device (as we keep this information coherent with the host, it influences performance on host-device copies, but some algorithms on the device might need to know the size of the buffer)
sizeOnDeviceReceive – if true, internal receive buffers must store their size additionally on the device

inline void addExchangeBuffer(const Mask &receive, const DataSpace<DIM> &dataSpace, uint32_t communicationTag, bool sizeOnDevice = false)

Add Exchange in dedicated memory space.

An Exchange is added to this GridBuffer. The exchange buffers use the their own memory instead of using the GridBuffer’s memory space.

Parameters:

receive – a Mask which describes the directions for the exchange
dataSpace – size of the newly created exchange buffer in each dimension
communicationTag – unique tag/id for communication
sizeOnDevice – if true, internal buffers must store their size additionally on the device (as we keep this information coherent with the host, it influences performance on host-device copies, but some algorithms on the device might need to know the size of the buffer)

inline bool hasSendExchange(uint32_t ex) const

Returns whether this GridBuffer has an Exchange for sending in ex direction.

Parameters:: ex – exchange direction to query
Returns:: true if send exchanges with ex direction exist, otherwise false

inline bool hasReceiveExchange(uint32_t ex) const

Returns whether this GridBuffer has an Exchange for receiving from ex direction.

Parameters:: ex – exchange direction to query
Returns:: true if receive exchanges with ex direction exist, otherwise false

inline Exchange<BORDERTYPE, DIM> &getSendExchange(uint32_t ex) const

Returns the Exchange for sending data in ex direction.

Returns an Exchange which for sending data from this GridBuffer in the direction described by ex.

Parameters:: ex – the direction to query
Returns:: the Exchange for sending data

inline Exchange<BORDERTYPE, DIM> &getReceiveExchange(uint32_t ex) const

Returns the Exchange for receiving data from ex direction.

Returns an Exchange which for receiving data to this GridBuffer from the direction described by ex.

Parameters:: ex – the direction to query
Returns:: the Exchange for receiving data

inline Mask getSendMask() const

Returns the Mask describing send exchanges.

Returns:: Mask for send exchanges

inline Mask getReceiveMask() const

Returns the Mask describing receive exchanges.

Returns:: Mask for receive exchanges

inline EventTask communication()

Starts sync data from own device buffer to neighbor device buffer.

Asynchronously starts synchronization data from internal DeviceBuffer using added Exchange buffers. This operation runs sequential to other code but intern asynchronous

inline EventTask asyncCommunication(EventTask serialEvent)

Starts sync data from own device buffer to neighbor device buffer.

Asynchronously starts synchronization data from internal DeviceBuffer using added Exchange buffers.

inline EventTask asyncSend(EventTask serialEvent, uint32_t sendEx)

inline EventTask asyncReceive(EventTask serialEvent, uint32_t recvEx)

inline GridLayout<DIM> getGridLayout()

Returns the GridLayout describing this GridBuffer.

Returns:: the layout of this buffer

Protected Attributes

bool hasOneExchange

uint32_t lastUsedCommunicationTag

GridLayout<DIM> gridLayout

Mask sendMask

Mask receiveMask

std::unique_ptr<Exchange<BORDERTYPE, DIM>> sendExchanges[27]

std::unique_ptr<Exchange<BORDERTYPE, DIM>> receiveExchanges[27]

EventTask receiveEvents[27]

EventTask sendEvents[27]

uint32_t maxExchange

SimulationFieldHelper

template<class CellDescription> class SimulationFieldHelper

Public Types

using MappingDesc = CellDescription 

Public Functions

inline SimulationFieldHelper(CellDescription description)

virtual ~SimulationFieldHelper() = default

virtual void reset(uint32_t currentStep) = 0: Reset is as well used for init.

virtual void syncToDevice() = 0: Synchronize data from host to device.

inline CellDescription getCellDescription() const

Public Static Attributes

static constexpr uint32_t dim = MappingDesc::Dim

Protected Attributes

CellDescription cellDescription

ParticlesBase

template<typename T_ParticleDescription, class T_MappingDesc, typename T_DeviceHeap> class ParticlesBase : public pmacc::SimulationFieldHelper<T_MappingDesc>

Public Types

using MappingDesc = T_MappingDesc 

using BufferType = ParticlesBuffer<ParticleDescription, typename MappingDesc::SuperCellSize, T_DeviceHeap, MappingDesc::Dim>

using FrameType = typename BufferType::FrameType

using FrameTypeBorder = typename BufferType::FrameTypeBorder

using ParticlesBoxType = typename BufferType::ParticlesBoxType

using HandleGuardRegion = typename ParticleDescription::HandleGuardRegion 

using SimulationDataTag = ParticlesTag

Public Functions

template<typename T_MapperFactory> inline void fillGaps(T_MapperFactory const &mapperFactory)

Fill gaps in an area defined by a mapper factory.

Template Parameters:: T_MapperFactory – factory type to construct a mapper that defines the area to process
Parameters:: mapperFactory – factory instance

inline void fillAllGaps()

inline void fillBorderGaps()

void deleteGuardParticles(uint32_t exchangeType)

template<uint32_t T_area> void deleteParticlesInArea()

void copyGuardToExchange(uint32_t exchangeType)

copy guard particles to intermediate exchange buffer

Copy all particles from the guard of a direction to the device exchange buffer.

Warning

This method resets the number of particles in the processed supercells even if there are particles left in the supercell and does not guarantee that the last frame is contiguous filled. Call fillAllGaps afterwards if you need a valid number of particles and a contiguously filled last frame.

void insertParticles(uint32_t exchangeType)

inline ParticlesBoxType getDeviceParticlesBox()

inline ParticlesBoxType getHostParticlesBox(const int64_t memoryOffset)

inline BufferType &getParticlesBuffer()

virtual void reset(uint32_t currentStep) override: Reset is as well used for init.

Public Static Attributes

static constexpr uint32_t dim = MappingDesc::Dim

Protected Functions

inline ParticlesBase(const std::shared_ptr<T_DeviceHeap> &deviceHeap, MappingDesc description)

inline ~ParticlesBase() override

template<uint32_t T_area> inline void shiftParticles(bool onlyProcessMustShiftSupercells)

Shift all particles in an area defined by a mapper factory.

The factory type must be such that StrideMapperFactory<T_MapperFactory, stride> is specialized

Parameters:: onlyProcessMustShiftSupercells – whether to process only supercells with mustShift set to true (optimization to be used with particle pusher) or process all supercells

template<typename T_MapperFactory> inline void shiftParticles(T_MapperFactory const &mapperFactory, bool onlyProcessMustShiftSupercells)

Shift all particles in the area defined by the given factory.

Note that the area itself is not strided, but the factory must produce stride mappers for the area.

Template Parameters:

T_strideMapperFactory – factory type to construct a stride mapper, resulting mapper must have stride of at least 3, adheres to the MapperFactory concept

Parameters:

mapperFactory – factory instance
onlyProcessMustShiftSupercells – whether to process only supercells with mustShift set to true (optimization to be used with particle pusher) or process all supercells

Protected Attributes

BufferType *particlesBuffer

ParticleDescription

template<typename T_Name, typename T_NumSlots, typename T_SuperCellSize, typename T_ValueTypeSeq, typename T_Flags = mp_list<>, typename T_HandleGuardRegion = HandleGuardRegion<particles::policies::ExchangeParticles, particles::policies::DeleteParticles>, typename T_MethodsList = mp_list<>, typename T_FrameExtensionList = mp_list<>> struct ParticleDescription

ParticleDescription defines attributes, methods and flags of a particle.

This class holds no runtime data. The class holds information about the name, attributes, flags and methods of a particle.

Template Parameters:

T_Name – name of described particle (e.g. electron, ion) type must be a PMACC_CSTRING
T_NumSlots – compile time size of a super cell
T_ValueTypeSeq – sequence or single type with value_identifier, must not have duplicates
T_Flags – sequence or single type with identifier to add flags on a frame, must not have duplicates
T_MethodsList – sequence or single class with particle methods (e.g. calculate mass, gamma, …) (e.g. useSolverXY, calcRadiation, …)
T_FrameExtensionList – sequence or single class with frame extensions
- extension must be an unary template class that supports boost::mpl::apply1<>
- type of the final frame is applied to each extension class (this allows pointers and references to a frame itself)
- the final frame that uses ParticleDescription inherits from all extension classes

Public Types

using Name = T_Name 

using NumSlots = T_NumSlots 

using SuperCellSize = T_SuperCellSize 

using ValueTypeSeq = ToSeq<T_ValueTypeSeq>

using FlagsList = ToSeq<T_Flags>

using HandleGuardRegion = T_HandleGuardRegion 

using MethodsList = ToSeq<T_MethodsList>

using FrameExtensionList = ToSeq<T_FrameExtensionList>

Public Functions

PMACC_CASSERT_MSG(_error_particles_must_not_have_duplicate_attributes____check_your_speciesDefinition_param_file, isUnique<ValueTypeSeq>)

PMACC_CASSERT_MSG(_error_particles_must_not_have_duplicate_flags____check_your_speciesDefinition_param_file, isUnique<FlagsList>)

ParticleBox

template<class T_Frame, typename T_DeviceHeapHandle, typename T_SuperCellSize, unsigned DIM> class ParticlesBox : protected pmacc::DataBox<PitchedBox<SuperCell<T_Frame, T_SuperCellSize>, DIM>>

A DIM-dimensional Box holding frames with particle data.

Template Parameters:

FRAME – datatype for frames
DIM – dimension of data (1-3)

Public Types

using FrameType = T_Frame 

using FramePtr = FramePointer<FrameType>

using SuperCellType = SuperCell<FrameType, T_SuperCellSize>

using BaseType = DataBox<PitchedBox<SuperCell<FrameType, T_SuperCellSize>, DIM>>

using SuperCellSize = T_SuperCellSize 

using DeviceHeapHandle = T_DeviceHeapHandle 

Public Functions

HDINLINE ParticlesBox() = default: default constructor

Warning

after this call the object is in a invalid state and must be initialized with an assignment of a valid ParticleBox

inline HDINLINE ParticlesBox(const DataBox<PitchedBox<SuperCellType, DIM>> &superCells, const DeviceHeapHandle &deviceHeapHandle)

inline HDINLINE ParticlesBox(const DataBox<PitchedBox<SuperCellType, DIM>> &superCells, const DeviceHeapHandle &deviceHeapHandle, int64_t memoryOffset)

template<typename T_Worker> inline DINLINE FramePtr getEmptyFrame (const T_Worker &worker)

Returns an empty frame from data heap.

Returns:: an empty frame

template<typename T_Worker> inline DINLINE void removeFrame (const T_Worker &worker, FramePtr &frame)

Removes frame from heap data heap.

Parameters:: frame – frame to remove

inline HDINLINE FramePtr mapPtr (FramePtr devPtr) const

inline HDINLINE FramePtr getNextFrame (const FramePtr &frame) const

Returns the next frame in the linked list.

Parameters:: frame – the active frame
Returns:: the next frame in the list

inline HDINLINE FramePtr getPreviousFrame (const FramePtr &frame) const

Returns the previous frame in the linked list.

Parameters:: frame – the active frame
Returns:: the previous frame in the list

inline HDINLINE FramePtr getLastFrame (const DataSpace< DIM > &idx) const

Returns the last frame of a supercell.

Parameters:: idx – position of supercell
Returns:: the last frame of the linked list from supercell

inline HDINLINE FramePtr getFirstFrame (const DataSpace< DIM > &idx) const

Returns the first frame of a supercell.

Parameters:: idx – position of supercell
Returns:: the first frame of the linked list from supercell

template<typename T_Worker> inline DINLINE void setAsFirstFrame (T_Worker const &worker, FramePtr &frame, DataSpace< DIM > const &idx)

Sets frame as the first frame of a supercell.

Parameters:

frame – frame to set as first frame
idx – position of supercell

template<typename T_Worker> inline DINLINE void setAsLastFrame (T_Worker const &worker, FramePointer< FrameType > &frame, DataSpace< DIM > const &idx)

Sets frame as the last frame of a supercell.

Parameters:

frame – frame to set as last frame
idx – position of supercell

template<typename T_Worker> inline DINLINE bool removeLastFrame (const T_Worker &worker, const DataSpace< DIM > &idx)

Removes the last frame of a supercell.

This call is not threadsave, only one thread from a supercell may call this function.

Parameters:: idx – position of supercell
Returns:: true if more frames in list, else false

inline decltype(auto) HDINLINE getSuperCell (DataSpace< DIM > idx) const

inline decltype(auto) HDINLINE getSuperCell (DataSpace< DIM > idx)

Public Static Attributes

static constexpr uint32_t frameSize = FrameType::NumSlots::value

static constexpr uint32_t Dim = DIM 

Frame

template<typename T_CreatePairOperator, typename T_ParticleDescription> struct Frame : protected pmacc::math::MapTuple<SeqToMap<T_ParticleDescription::ValueTypeSeq, T_CreatePairOperator>::type>, public pmacc::InheritLinearly<mp_append<T_ParticleDescription::MethodsList, OperateOnSeq<T_ParticleDescription::FrameExtensionList, boost::mpl::apply1<boost::mpl::_1, Frame<T_CreatePairOperator, T_ParticleDescription>>>::type>>

Frame is a storage for arbitrary number >0 of Particles with attributes.

IPlugin

class IPlugin : public pmacc::INotify

Subclassed by pmacc::SimulationHelper< simDim >, picongpu::ISimulationPlugin, picongpu::ISimulationStarter, picongpu::MetadataAggregator, picongpu::plugins::binning::Binner< TBinningData >, pmacc::SimulationHelper< DIM >

Public Functions

IPlugin() = default

~IPlugin() override = default

inline virtual void load()

inline virtual void unload()

inline bool isLoaded()

virtual void checkpoint(uint32_t currentStep, const std::string checkpointDirectory) = 0

Notifies plugins that a (restartable) checkpoint should be created for this timestep.

Parameters:

currentStep – cuurent simulation iteration step
checkpointDirectory – common directory for checkpoints

virtual void restart(uint32_t restartStep, const std::string restartDirectory) = 0

Restart notification callback.

Parameters:

restartStep – simulation iteration step to restart from
restartDirectory – common restart directory (contains checkpoints)

virtual void pluginRegisterHelp(po::options_description &desc) = 0

Register command line parameters for this plugin.

Parameters are parsed and set prior to plugin load.

Parameters:: desc – boost::program_options description

virtual std::string pluginGetName() const = 0

Return the name of this plugin for status messages.

Returns:: plugin name

inline virtual void onParticleLeave(const std::string&, const int32_t)

Called each timestep if particles are leaving the global simulation volume.

This method is only called for species which are marked with the GuardHandlerCallPlugins policy in their descpription.

The order in which the plugins are called is undefined, so this means read-only access to the particles.

Parameters:

speciesName – name of the particle species
direction – the direction the particles are leaving the simulation

inline uint32_t getLastCheckpoint() const

When was the plugin checkpointed last?

Returns:: last checkpoint’s time step

inline void setLastCheckpoint(uint32_t currentStep)

Remember last checkpoint call.

Parameters:: currentStep – current simulation iteration step

Protected Functions

inline virtual void pluginLoad()

inline virtual void pluginUnload()

Protected Attributes

bool loaded = {false}

uint32_t lastCheckpoint = {0}

PluginConnector

class PluginConnector

Plugin registration and management class.

Public Functions

void registerPlugin(IPlugin *plugin)

Register a plugin for loading/unloading and notifications.

Plugins are loaded in the order they are registered and unloaded in reverse order. To trigger plugin notifications, call

SimulationHelper

template<unsigned DIM> class SimulationHelper : public pmacc::IPlugin 

Abstract base class for simulations.

Use this helper class to write your own concrete simulations by binding pure virtual methods.

Template Parameters:: DIM – base dimension for the simulation (2-3)

Public Types

using SeqOfTimeSlices = std::vector<pluginSystem::Slice>

Public Functions

SimulationHelper(): Constructor.

~SimulationHelper() override

virtual void runOneStep(uint32_t currentStep) = 0

Must describe one iteration (step).

This function is called automatically.

virtual void init() = 0

Initialize simulation.

Does hardware selections/reservations, memory allocations and initializes data structures as empty.

virtual uint32_t fillSimulation() = 0

Fills simulation with initial data after init()

Returns:: returns the first step of the simulation (can be >0 for, e.g., restarts from checkpoints)

virtual void resetAll(uint32_t currentStep) = 0

Reset the simulation to a state such as it was after init() but for a specific time step.

Can be used to call fillSimulation() again.

virtual void movingWindowCheck(uint32_t currentStep) = 0

Check if moving window work must do.

If no moving window is needed the implementation of this function can be empty

Parameters:: currentStep – simulation step

void notifyPlugins(uint32_t currentStep)

Call all plugins.

This function is called inside the simulation loop.

Parameters:: currentStep – simulation step

virtual void dumpOneStep(uint32_t currentStep)

Write a checkpoint if needed for the given step.

This function is called inside the simulation loop.

Parameters:: currentStep – simulation step

inline GridController<DIM> &getGridController()

void dumpTimes(TimeIntervall &tSimCalculation, TimeIntervall&, double &roundAvg, uint32_t currentStep)

virtual void startSimulation(): Begin the simulation.

virtual void pluginRegisterHelp(po::options_description &desc) override

Register command line parameters for this plugin.

Parameters are parsed and set prior to plugin load.

Parameters:: desc – boost::program_options description

inline virtual std::string pluginGetName() const override

Return the name of this plugin for status messages.

Returns:: plugin name

virtual void pluginLoad() override

inline virtual void pluginUnload() override

inline virtual void restart(uint32_t, const std::string) override

Restart notification callback.

Parameters:

restartStep – simulation iteration step to restart from
restartDirectory – common restart directory (contains checkpoints)

inline virtual void checkpoint(uint32_t, const std::string) override

Notifies plugins that a (restartable) checkpoint should be created for this timestep.

Parameters:

currentStep – cuurent simulation iteration step
checkpointDirectory – common directory for checkpoints

Protected Functions

std::vector<uint32_t> readCheckpointMasterFile()

Reads the checkpoint master file if any and returns all found checkpoint steps.

Returns:: vector of found checkpoints steps in order they appear in the file

Protected Attributes

uint32_t runSteps = {0}

uint32_t softRestarts: Presentations: loop the whole simulation softRestarts times from initial step to runSteps.

std::string checkpointPeriod

SeqOfTimeSlices seqCheckpointPeriod

std::uint64_t checkpointPeriodMinutes = 0u

std::thread checkpointTimeThread

std::condition_variable exitConcurrentThreads

std::mutex concurrentThreadMutex

std::string checkpointDirectory

uint32_t numCheckpoints = {0}

int32_t restartStep = {-1}

std::string restartDirectory

bool restartRequested = {false}

const std::string CHECKPOINT_MASTER_FILE

std::string author

bool useMpiDirect = {false}: enable MPI gpu direct

bool tryRestart = false

ForEach

template<typename List, typename T_Functor, typename T_Accessor = meta::accessors::Identity<>> struct ForEach

Compile-Time for each for Boost::MPL Type Lists.

Example: List = pmacc::mp_list<int,float> Functor = any unary lambda functor Accessor = lambda operation identity

definition: F(X) means boost::apply<F,X>

call: ForEach<List,Functor,Accessor>()(42); unrolled code: Functor(Accessor(int))(42); Functor(Accessor(float))(42);

Template Parameters:

List – An mp_list.
T_Functor – An unary lambda functor with a HDINLINE void operator()(…) method _1 is substituted by Accessor’s result using boost::mpl::apply with elements from T_MPLSeq. The maximum number of parameters for the operator() is limited by PMACC_MAX_FUNCTOR_OPERATOR_PARAMS
T_Accessor – An unary lambda operation

Public Types

template<typename X> using ReplacePlaceholder = typename boost::mpl::apply1<T_Functor, typename boost::mpl::apply1<T_Accessor, X>::type>::type

using SolvedFunctors = mp_transform<ReplacePlaceholder, List>

Public Functions

template<typename... T_Types> inline HDINLINE void operator() (T_Types &&... ts) const

Kernel Start

Warning

doxygenstruct: Cannot find class “pmacc::exec::Kernel” in doxygen xml output for project “PIConGPU” from directory: ../xml

PMACC_KERNEL(...)

Create a kernel object out of a functor instance.

This macro add the current filename and line number to the kernel object.

Identifier

Construct unique types, e.g. to name, access and assign default values to particle species’ attributes. See for example PIConGPU’s speciesAttributes.param for usage.

value_identifier(in_type, name, in_default)

define a unique identifier with name, type and a default value

The created identifier has the following options: getValue() - return the user defined value getName() - return the name of the identifier ::type - get type of the value

e.g. value_identifier(float,length,0.0f) typedef length::type value_type; // is float value_type x = length::getValue(); //set x to 0.f printf(“Identifier name: %s”,length::getName()); //print Identifier name: length

to create a instance of this value_identifier you can use: length() or length_

Parameters:

in_type – type of the value
name – name of identifier
in_value – user defined value of in_type (can be a constructor of a class)

alias(name)

create an alias

an alias is a unspecialized type of an identifier or a value_identifier

example: alias(aliasName); //create type varname

to specialize an alias do: aliasName<valueIdentifierName> to create an instance of this alias you can use: aliasName(); or aliasName_

get type which is represented by the alias typedef typename traits::Resolve<name>::type resolved_type;

Parameters:

name – name of alias