Algorithms#

This section contains functionality which is particle-adjacent. For example numerical methods used by particle based models and implementations of methods which use particles.

General#

This section contains commonly desired functionality that is implemented already in the library.

template<typename GROUP_TYPE, typename VALUE_TYPE>
void get_npart_cell(
std::shared_ptr<GROUP_TYPE> particle_sub_group,
CellDatConstSharedPtr<VALUE_TYPE> cell_dat_const,
const int row = 0,
const int col = 0
)#

Get the number of particles in each cell as a CellDatConst.

Parameters:

  • particle_sub_group – Particle{Sub}Group containing particles.

  • cell_dat_const – CellDatConst to populate with particle counts.

  • row – Row to populate in the CellDatConst.

  • col – Column to populate in the CellDatConst.

template<typename T, typename KERNEL_TYPE, typename ...DAT_ARGS>
inline void cell_dat_const_loop_element_wise(
CellDatConstSharedPtr<T> result_dat,
KERNEL_TYPE kernel,
DAT_ARGS... dat_args
)#

Applies a kernel element wise to the input CellDatConst dats and assigns the output to the result dat. 

// For CellDatConstSharedPtrs a,b,c and d.
cell_dat_const_loop_element_wise(
    d,
// This kernel is executed element wise.
    [=](auto a, auto b, auto c){
return a * b + c;
    },
    a, b, c
);
If the output dat, d, has shape NxM and if any arguments have nrow==1 and ncol==1 then these single values are logically broadcast to size NxM.

Parameters:

  • result_dat – CellDatConst to be overwritten with the result of the operation. May be equal to one of the arguments to the kernel.

  • kernel – Kernel to apply element wise to compute the result. The parameters of the kernel should be scalar types correpsonding to each of the remaining arguments of this function.

  • dat_args – CellDatConstSharedPtrs which provide the elements to pass to the kernel.

template<typename GROUP_TYPE>
inline void forward_euler(
std::shared_ptr<GROUP_TYPE> particle_sub_group,
Sym<REAL> position,
const REAL dt,
Sym<REAL> velocity
)#

Perform one step of Forward Euler integration.

Parameters:

  • particle_sub_group – Particle{Sub}Group containing particles.

  • position – Sym of particle positions.

  • dt – Timestep size.

  • velocity – Sym of particle velocities.

template<typename T, std::size_t N, typename KERNEL_TYPE, typename ...ARRAY_ARGS>
inline void nd_local_array_loop_element_wise(
NDLocalArraySharedPtr<T, N> result_array,
KERNEL_TYPE kernel,
ARRAY_ARGS... array_args
)#

Applies a kernel element wise to the input NDLocalArrays and assigns the output to the result local array. 

// For NDLocalArraySharedPtrs a,b,c and d.
nd_local_array_loop_element_wise(
    d,
// This kernel is executed element wise.
    [=](auto a, auto b, auto c){
return a * b + c;
    },
    a, b, c
);
If the output array, d, has shape NxM and if any arguments have nrow==1 and ncol==1 then these single values are logically broadcast to size NxM.

Parameters:

  • result_array – NDLocalArray to be overwritten with the result of the operation. May be equal to one of the arguments to the kernel.

  • kernel – Kernel to apply element wise to compute the result. The parameters of the kernel should be scalar types correpsonding to each of the remaining arguments of this function.

  • array_args – NDLocalArraySharedPtrs which provide the elements to pass to the kernel.

template<typename T>
void copy_ephemeral_dat_to_particle_dat(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<T> sym_src,
Sym<T> sym_dst
)#

Copy all particle data from an EphemeralDat to a ParticleDat. The source and destination dats must exist and have the same number of components. Source and destination dats may share the same name.

Parameters:

  • particle_sub_group – ParticleSubGroup containing source and destination dats.

  • sym_src – Source EphemeralDat name.

  • sym_dst – Destination ParticleDat name.

template<typename T>
void copy_particle_dat_to_ephemeral_dat(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<T> sym_src,
Sym<T> sym_dst
)#

Copy all particle data from a ParticleDat to an EphemeralDat. The source and destination dats must exist and have the same number of components. Source and destination dats may share the same name.

Parameters:

  • particle_sub_group – ParticleSubGroup containing source and destination dats.

  • sym_src – Source ParticleDat name.

  • sym_dst – Destination EphemeralDat name.

template<typename GROUP_TYPE, typename SYM_TYPE, typename VALUE_TYPE>
void cellwise_broadcast(
std::shared_ptr<GROUP_TYPE> group,
Sym<SYM_TYPE> sym,
const int component,
const std::vector<VALUE_TYPE> &values
)#

Set the specified component and property on all particles to the value in the passed array at the index that corresponds to the cell of the particle.

Parameters:

  • group – ParticleGroup or ParticleSubGroup of particles to set values for.

  • sym – Particle property to set.

  • component – Particle component to set.

  • values – Vector of values to set cell wise.

template<typename T>
inline void fill(
ParticleGroupSharedPtr particle_group,
Sym<T> sym,
const T value,
std::optional<int> component = std::nullopt
)#

Fill a ParticleDat with the specified value.

Parameters:

  • particle_group – ParticleGroup containing ParticleDat to fill.

  • sym – Sym<INT> or Sym<REAL> of ParticleDat to fill.

  • value – INT or REAL value to fill ParticleDat with.

  • component – Optionally specifify the component of the ParticleDat to fill.

template<typename T>
inline void fill(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<T> sym,
const T value,
std::optional<int> component = std::nullopt
)#

Fill a ParticleDat with the specified value.

Parameters:

  • particle_sub_group – ParticleSubGroup containing ParticleDat to fill.

  • sym – Sym<INT> or Sym<REAL> of ParticleDat to fill.

  • value – INT or REAL value to fill ParticleDat with.

  • component – Optionally specifify the component of the ParticleDat to fill.

template<typename GROUP_TYPE, typename T, typename OP>
void reduce_dat_component_cellwise(
std::shared_ptr<GROUP_TYPE> particle_sub_group,
Sym<T> sym,
const int sym_component,
CellDatConstSharedPtr<T> cell_dat_const,
const int cell_dat_const_row,
const int cell_dat_const_col,
OP op
)#

Reduces a single value from each particle into a specified CellDatConst index.

Parameters:

  • particle_sub_group – [in] ParticleGroup or ParticleSubGroup providing source particles.

  • sym – [in] Specify the source particle property.

  • sym_component – [in] Specify the index in the particle property to reduce.

  • cell_dat_const – [inout] The output CellDatConst to reduce into. The reduced values from the particles will be combined with the value already in the CellDatConst.

  • cell_dat_const_row – [in] The row to reduce into of the CellDatConst.

  • cell_dat_const_col – [in] The column to reduce into of the CellDatConst.

  • op – [in] Binary operation to apply.

template<typename GROUP_TYPE, typename T, typename OP>
void reduce_dat_components_cellwise(
std::shared_ptr<GROUP_TYPE> particle_sub_group,
Sym<T> sym,
CellDatConstSharedPtr<T> cell_dat_const,
OP op
)#

Reduces all particle properties for a given property into a CellDatConst cellwise. CellDatConst elements are indexed row-wise. The total number of CellDatConst elements must match the number of components of the particle property.

Parameters:

  • particle_sub_group – [in] ParticleGroup or ParticleSubGroup providing source particles.

  • sym – [in] Specify the source particle property.

  • cell_dat_const – [inout] The output CellDatConst to reduce into. The reduced values from the particles will be combined with the value already in the CellDatConst.

  • op – [in] Binary operation to apply.

DSMC#

This section contains functionality for implementing DSMC style methods.

class CollisionCellPartition#
#include <collision_cell_partition.hpp>

Holds a map from (mesh cell, collision cell, species ID) to particle layers. Particles may be masked off by passing a ParticleMask to the construct call. Particles exist in the map independently of the mask values.

Public Functions

CollisionCellPartition(const CollisionCellPartition &st) = delete#

Disable (implicit) copies.

CollisionCellPartition &operator=(
CollisionCellPartition const &a
) = delete#

Disable (implicit) copies.

CollisionCellPartition(
SYCLTargetSharedPtr sycl_target,
const int num_mesh_cells,
std::vector<INT> species_ids
)#

Create a container that holds a representation of particles partitioned into mesh cells then DSMC collision cells.

Parameters:

  • sycl_target – SYCLTarget to use.

  • num_mesh_cells – Number of local mesh cells (not the number of collision cells).

  • species_ids – Vector containing all permissible species IDs that could be encountered.

void construct(
ParticleSubGroupSharedPtr particle_sub_group,
const std::vector<int> &num_collision_cells,
Sym<INT> species_id_sym,
const int species_id_component,
Sym<INT> collision_cell_sym,
const int collision_cell_component
)#

Construct the internal representation from a ParticleSubGroup. This construct method enables all particles, i.e. there are no masks values used.

Parameters:

  • particle_sub_group – The set of particles which are partitioned into species and dsmc cells.

  • num_collision_cells – Vector of length num_mesh_cells containing the number of collision cells in each mesh cell.

  • species_id_sym – Sym describing which ParticleDat contains the species ID.

  • species_id_component – Describe which ParticleDat component describes the species.

  • collision_cell_sym – Sym describing which ParticleDat contains the collision cell ID.

  • collision_cell_component – Describe which ParticleDat component contains the collision cell ID.

void construct(
ParticleSubGroupSharedPtr particle_sub_group,
ParticleMaskSharedPtr particle_mask,
const std::vector<int> &num_collision_cells,
Sym<INT> species_id_sym,
const int species_id_component,
Sym<INT> collision_cell_sym,
const int collision_cell_component
)#

Construct the internal representation from a ParticleSubGroup. Particles may be masked off, or on, from pair selection after construct is called by updating the ParticleMask that is passed here. Particles exist in this data structure indpendently of the mask value. The current value of the mask is taken into account when get_max_num_pairs is called.

Parameters:

  • particle_sub_group – The set of particles which are partitioned into species and dsmc cells.

  • particle_mask – Particle masks that indicate if a particle is available.

  • num_collision_cells – Vector of length num_mesh_cells containing the number of collision cells in each mesh cell.

  • species_id_sym – Sym describing which ParticleDat contains the species ID.

  • species_id_component – Describe which ParticleDat component describes the species.

  • collision_cell_sym – Sym describing which ParticleDat contains the collision cell ID.

  • collision_cell_component – Describe which ParticleDat component contains the collision cell ID.

void get_max_num_pairs(
const INT species_id_a,
const INT species_id_b,
const bool replacement,
NDLocalArraySharedPtr<int, 2> &map_cell_to_num_pairs
)#

Determine the maximum number of pairs that can be formed between species A and B for each collision cell. Note that in the case of replacement these values are identical to determining if there are two or more particles in the collision cell. In this scenario the return values are 0 or INT_MAX. This method will use the current values of the ParticleMask provided if a ParticleMask was provided at construction time.

Parameters:

  • species_id_a – [in] Species ID of A.

  • species_id_b – [in] Species ID of B.

  • replacement – [in] Indicate if pairs are chosen with (true) or without replacement (false).

  • map_cell_to_num_pairs – [inout] Output map from [mesh cell][collision cell] to maximum number of pairs that can be formed.

void get_max_num_pairs(
const INT species_id_a,
const INT species_id_b,
const bool replacement,
NDHostArraySharedPtr<int, 2> &map_cell_to_num_pairs
)#

Determine the maximum number of pairs that can be formed between species A and B for each collision cell. Note that in the case of replacement these values are identical to determining if there are two or more particles in the collision cell. In this scenario the return values are 0 or INT_MAX. This method will use the current values of the ParticleMask provided if a ParticleMask was provided at construction time.

Parameters:

  • species_id_a – [in] Species ID of A.

  • species_id_b – [in] Species ID of B.

  • replacement – [in] Indicate if pairs are chosen with (true) or without replacement (false).

  • map_cell_to_num_pairs – [inout] Output map from [mesh cell][collision cell] to maximum number of pairs that can be formed.

INT get_linear_species_id(const INT species_id)#
Parameters:

species_id – Species ID as stored on particles.

Returns:

Linear species ID as used in the device maps.

CollisionCellPartitionDevice get_device()#
Returns:

The device description of the maps.

NDIndex<2> get_collision_cell_num_pairs_shape()#
Returns:

A NDIndex<2> instance suitably sized for the number of mesh cells and collision cells currently specified.

ParticleMaskSharedPtr get_particle_mask()#
Returns:

The current ParticleMask in use. This method may return a nullptr.

void get_num_unmasked_particles(
const INT species_id,
NDHostArraySharedPtr<int, 2> &num_particles
)#

Get the number of unmasked particles of a particular species ID in each collision cell.

Parameters:

  • species_id – [in] Species ID of particles to get number of.

  • num_particles – [inout] NDHostArray of particle numbers per collision cell. Should be of dimension 2 with extents num_mesh_cells and max_num_collision_cells. Will be allocated if nullptr.

void get_num_unmasked_particles(
const INT species_id,
NDLocalArraySharedPtr<int, 2> &num_particles
)#

Get the number of unmasked particles of a particular species ID in each collision cell.

Parameters:

  • species_id – [in] Species ID of particles to get number of.

  • num_particles – [inout] NDLocalArray of particle numbers per collision cell. Should be of dimension 2 with extents num_mesh_cells and max_num_collision_cells. Will be allocated if nullptr.

class CollisionCellRateReduction#
#include <collision_cell_rate_reduction.hpp>

Implementation to reduce rates on a collision cell basis.

Rates are reduced per collision cell as 

rate_{cell} = sum_{pair lists} (max_{pairs in cell} (pair reaction rate))

Public Functions

CollisionCellRateReduction(
const CollisionCellRateReduction &st
) = delete#

Disable (implicit) copies.

CollisionCellRateReduction &operator=(
CollisionCellRateReduction const &a
) = delete#

Disable (implicit) copies.

CollisionCellRateReduction(
CollisionCellPartitionSharedPtr collision_cell_partition
)#

Create a new reduction object for pairs of particles created using the passed CollisionCellPartition.

Parameters:

collision_cell_partition – CollisionCellPartition from which pairs are sampled.

void setup(const int num_contributors)#

Prepare the internal implementation (reallocate) for N contributing entities, e.g. reactions. Clears all internal state. Contributors are referenced in later calls using an integer in [0, N).

Parameters:

num_contributors – Number of contributors.

void resize()#

Resize the internal buffers to be of size num_mesh_cells x max_num_collision_cells as given by the CollisionCellPartition.

void update(
const int contributor_id,
CellwisePairListAbsolute<ParticleGroup, CellwisePairList> &pair_list,
const int cell_start,
const int cell_end,
Sym<INT> collision_cell_sym,
const int collision_cell_component,
LocalArraySharedPtr<REAL> device_rate_buffer
)#

Update the internal representation for a contributor by submiting a set of pairs and corresponding rates into the reduction instance. This call will populate the entries in [cell_start, cell_end) of the accumulation buffer for the contributor. For each collision cell the maximum rate supplied in the device rate buffer and the maximum already stored in the internal representation will be stored in the internal representation.

Parameters:

  • contributor_id – Index of contributor.

  • pair_list – Pair list describing pairs.

  • cell_start – First cell of cell block.

  • cell_end – Last cell plus one of cell block.

  • collision_cell_sym – ParticleDat containing the collision cell index.

  • collision_cell_component – ParticleDat component containing the collision cell index.

  • device_rate_buffer – LocalArray containing a rate per pair in the pair list only for the pairs in [cell_start, cell_end). i.e. This buffer will be indexed using the loop linear index not the pair list linear index.

void update(
const int contributor_id,
CellwisePairListAbsolute<ParticleGroup, CellwisePairList> &pair_list,
const int cell_start,
const int cell_end,
Sym<INT> collision_cell_sym,
const int collision_cell_component,
LocalArraySharedPtr<REAL> device_rate_buffer,
const std::vector<int> &cell_mask,
const REAL rate_init
)#

Update the internal representation for a contributor by submiting a set of pairs and corresponding rates into the reduction instance. This call will populate the entries in [cell_start, cell_end) of the accumulation buffer for the contributor. For each collision cell the maximum rate supplied in the device rate buffer and the maximum already stored in the internal representation will be stored in the internal representation.

For mesh cells masked as true in the cell mask vector the supplied initial rate will be used to populate the internal buffer for that contributor rather than the rates indexed by pairs.

Parameters:

  • contributor_id – Index of contributor.

  • pair_list – Pair list describing pairs.

  • cell_start – First cell of cell block.

  • cell_end – Last cell plus one of cell block.

  • collision_cell_sym – ParticleDat containing the collision cell index.

  • collision_cell_component – ParticleDat component containing the collision cell index.

  • device_rate_buffer – LocalArray containing a rate per pair in the pair list only for the pairs in [cell_start, cell_end). i.e. This buffer will be indexed using the loop linear index not the pair list linear index.

  • cell_mask – Vector of length num_mesh_cells that is used as a mask for which mesh cells should be set to the initial rate.

  • rate_init – Rate to set for all collision cells in mesh cells where the mask is non-zero.

void update(
const int contributor_id,
const std::vector<int> &cell_mask,
const REAL rate_init
)#

For mesh cells masked as true in the cell mask vector the supplied initial rate will be used to populate the internal buffer for that contributor rather than the pairs.

Parameters:

  • contributor_id – Index of contributor.

  • cell_mask – Vector of length num_mesh_cells that is used as a mask for which mesh cells should be set to the initial rate.

  • rate_init – Rate to set for all collision cells in mesh cells where the mask is non-zero.

void get(NDLocalArraySharedPtr<REAL, 2> &accumulated_rates)#

Get the current accumulated rates in a 2D NDLocalArray of size (num_mesh_cells) x (max_num_collision_cells).

Parameters:

accumulated_rates – [inout] Buffer for reduced rates. Will be allocated if nullptr.

class PairSamplerNoReplacement : public NESO::Particles::CellwisePairList#
#include <pair_sampler_no_replacement.hpp>

Class for sampling pairs of particles without replacement within a collision cell.

Public Functions

PairSamplerNoReplacement(const PairSamplerNoReplacement &st) = delete#

Disable (implicit) copies.

PairSamplerNoReplacement &operator=(
PairSamplerNoReplacement const &a
) = delete#

Disable (implicit) copies.

PairSamplerNoReplacement(
SYCLTargetSharedPtr sycl_target,
const int num_mesh_cells,
std::shared_ptr<RNGGenerationFunction<REAL>> rng_generation_function
)#

Create a sampler for a given compute target and mesh cell count.

Parameters:

  • sycl_target – Compute device to use.

  • num_mesh_cells – Mesh cell count.

  • rng_generation_function – Source of random samples.

void sample(
CollisionCellPartitionSharedPtr collision_cell_partition,
const INT species_id_a,
const INT species_id_b,
NDLocalArraySharedPtr<int, 2> &map_cell_to_num_pairs
)#

Sample pairs in each collision cell between species A and B.

Parameters:

  • collision_cell_partition – Map from collision cells to particles within those collision cells.

  • species_id_a – First species ID.

  • species_id_b – Second species ID.

  • map_cell_to_num_pairs – Map from mesh cell to counts for each collision cell.

void sample(
CollisionCellPartitionSharedPtr collision_cell_partition,
const INT species_id_a,
const INT species_id_b,
NDHostArraySharedPtr<int, 2> &map_cell_to_num_pairs
)#

Sample pairs in each collision cell between species A and B.

Parameters:

  • collision_cell_partition – Map from collision cells to particles within those collision cells.

  • species_id_a – First species ID.

  • species_id_b – Second species ID.

  • map_cell_to_num_pairs – Map from mesh cell to counts for each collision cell.

virtual CellwisePairListDevice get_pair_list() override#

Get a description of the pair list accessible on the device.

Returns:

PairListDevice describing all the particle pairs. The returned object must have a lifetime equal or shorter than this host instance.

virtual CellwisePairListHostMap get_host_pair_list() override#

Get a description of the pair list accessible on the host.

Returns:

Container of pairs for each cell.

virtual INT get_num_pairs() override#
Returns:

The number of pairs in the pair list.

virtual PairMaskSharedPtr get_pair_mask() override#
Returns:

The PairMask which can be used to mask off pairs. By default all pairs will be enabled.

class SubdivideCartesianCells#
#include <subdivide_cartesian_cells.hpp>

Implementation to bin particles into subdivision of CartesianHMesh cells. For each mesh cell D subdivisions are performed in each dimension. The subdivided cells are linearly indexed lexicographically from fastest to slowest.

Public Functions

SubdivideCartesianCells(
SYCLTargetSharedPtr sycl_target,
CartesianHMeshSharedPtr mesh,
std::vector<int> &sub_cell_count
)#

Create new instance with provided mesh and number of subdivisions.

Parameters:

  • sycl_target – Compute device.

  • mesh – CartesianHMesh instance to subdivide cells of.

  • sub_cell_count – Vector containing the number of subdivisions for each mesh cell.

template<typename GROUP_TYPE>
inline void map(
std::shared_ptr<GROUP_TYPE> particle_sub_group,
Sym<INT> sym_name,
const int sym_component
)#

Map particles to subdivided cells.

Parameters:

  • particle_sub_group – Particle{Sub}Group of particles.

  • sym_name – Output Sym in which to store subdivision cell.

  • sym_component – Output component in which to store subdivision cell.

const std::vector<int> &get_num_subdivision_cells()#
Returns:

The total number of subdivision cells in each mesh cell.

Public Members

SYCLTargetSharedPtr sycl_target#

Compute device.

CartesianHMeshSharedPtr mesh#

The mesh on which the subdivisions are defined.

std::vector<int> sub_cell_count#

The number of subdivisions per dimension in each cell plus 1.

class SubdivideCellsVoronoi#
#include <subdivide_cells_voronoi.hpp>

Implementation for subdividing mesh cells into voronoi cells defined by points.

Public Functions

SubdivideCellsVoronoi(
SYCLTargetSharedPtr sycl_target,
CellDatSharedPtr<REAL> points
)#

Create new instance using a compute device and set of points. For a D-dimenionsal mesh N points should be specified as a NxD matrix per mesh cell. i.e. point per row.

Parameters:

  • sycl_target – Compute target.

  • points – Points, given mesh cell-wise, that define the Voronoi cells.

template<typename GROUP_TYPE>
inline void map(
std::shared_ptr<GROUP_TYPE> particle_sub_group,
Sym<INT> sym_name,
const int sym_component
)#

Map particles to Voronoi cells. If no Voronoi cells are specified for a mesh cell then the particles in that mesh cell are assigned to the 0-th Voronoi cell.

Parameters:

  • particle_sub_group – Particle{Sub}Group of particles.

  • sym_name – Output Sym in which to store Voronoi cell.

  • sym_component – Output component in which to store Voronoi cell.

const std::vector<int> &get_num_subdivision_cells()#
Returns:

The number of Voronoi cells in each mesh cell.

Public Members

SYCLTargetSharedPtr sycl_target#

Compute device.

CellDatSharedPtr<REAL> points#

Voronoi cell points.