Particle Sub Group#

These are helper functions and classes for working with ParticleSubGroups.

Helper Functions#

Here are helper functions for working with ParticleSubGroups.

inline auto get_particle_group(
ParticleSubGroupSharedPtr particle_sub_group
)#

Helper function to return the underlying ParticleGroup for a type.

Parameters:

particle_sub_group – ParticleSubGroup.

Returns:

Underlying ParticleGroup.

inline auto get_particle_group(ParticleGroupSharedPtr particle_group)#

Helper function to return the underlying ParticleGroup for a type.

Parameters:

particle_group – ParticleGroup.

Returns:

Underlying ParticleGroup.

inline constexpr bool is_particle_sub_group(
ParticleGroupSharedPtr &p
)#

Helper function for determining if a templated type is a ParticleGroup or ParticleSubGroup.

Parameters:

p – ParticleGroupSharedPtr.

Returns:

False.

inline constexpr bool is_particle_sub_group(
ParticleSubGroupSharedPtr &p
)#

Helper function for determining if a templated type is a ParticleGroup or ParticleSubGroup.

Parameters:

p – ParticleSubGroupSharedPtr.

Returns:

True.

Creation Functions#

Here are functions for creating ParticleSubGroups.

std::shared_ptr<ParticleSubGroup> particle_sub_group_discard(
std::shared_ptr<ParticleGroup> particle_group,
const int num_particles,
const bool make_static = false
)#

Create a ParticleSubGroup from a parent by discarding the first n particles in each cell.

Parameters:

  • particle_group – Particle(Sub)Group which is the parent.

  • num_particles – Number of particles to discard from each cell.

  • make_static – Make the ParticleSubGroup static (default false).

std::shared_ptr<ParticleSubGroup> particle_sub_group_discard(
std::shared_ptr<ParticleSubGroup> particle_sub_group,
const int num_particles,
const bool make_static = false
)#

Create a ParticleSubGroup from a parent by discarding the first n particles in each cell.

Parameters:

  • particle_sub_group – Particle(Sub)Group which is the parent.

  • num_particles – Number of particles to discard from each cell.

  • make_static – Make the ParticleSubGroup static (default false).

std::shared_ptr<ParticleSubGroup> particle_sub_group_disjoint_union(
std::vector<std::shared_ptr<ParticleSubGroup>> &parents,
const bool make_static = false
)#

Creates a sub group which is the union of N disjoint sub groups. This is useful when removing particles from multiple sub groups at the same time to avoid invalidation issues.

Parameters:

  • parents – Disjoint ParticleSubGroups to unionise.

  • make_static – Make the ParticleSubGroup static (default false).

Returns:

Union of input particle sub groups.

template<typename PARENT, typename KERNEL, typename ...ARGS>
inline ParticleSubGroupSharedPtr particle_sub_group(
std::shared_ptr<PARENT> parent,
KERNEL kernel,
ARGS... args
)#

Create a ParticleSubGroup based on a kernel and arguments. The selector kernel must be a lambda which returns true for particles which are in the sub group and false for particles which are not in the sub group. The arguments for the selector kernel must be read access Syms, i.e. Access::read(Sym<T>(“name”)).

For example if A is a ParticleGroup with an INT ParticleProp “ID” that holds particle ids then the following line creates a ParticleSubGroup from the particles with even ids. 

auto A_even = std::make_shared<ParticleSubGroup>(
  A, [=](auto ID) {
return ((ID[0] % 2) == 0);
  },
Access::read(Sym<INT>("ID")));

Parameters:

  • parent – Parent ParticleGroup or ParticleSubGroup from which to form ParticleSubGroup.

  • kernel – Lambda function (like a ParticleLoop kernel) that returns true for the particles which should be in the ParticleSubGroup.

  • args – Arguments in the form of access descriptors wrapping objects to pass to the kernel.

template<typename PARENT>
inline ParticleSubGroupSharedPtr particle_sub_group(
std::shared_ptr<PARENT> parent
)#

Create a ParticleSubGroup which is simply a reference/view into an entire ParticleGroup. This constructor creates a sub-group which is equivalent to 

auto A_all = std::make_shared<ParticleSubGroup>(
  A, [=]() {
return true;
  }
);
but can make additional optimisations.

Parameters:

parent – Parent ParticleGroup or ParticleSubGroup from which to form ParticleSubGroup.

template<typename PARENT, typename KERNEL, typename ...ARGS>
inline ParticleSubGroupSharedPtr static_particle_sub_group(
std::shared_ptr<PARENT> parent,
KERNEL kernel,
ARGS... args
)#

Create a static ParticleSubGroup based on a kernel and arguments. The selector kernel must be a lambda which returns true for particles which are in the sub group and false for particles which are not in the sub group. The arguments for the selector kernel must be read access Syms, i.e. Access::read(Sym<T>(“name”)).

For example if A is a ParticleGroup with an INT ParticleProp “ID” that holds particle ids then the following line creates a ParticleSubGroup from the particles with even ids. 

auto A_even = std::make_shared<ParticleSubGroup>(
  A, [=](auto ID) {
return ((ID[0] % 2) == 0);
  },
Access::read(Sym<INT>("ID")));

Parameters:

  • parent – Parent ParticleGroup or ParticleSubGroup from which to form ParticleSubGroup.

  • kernel – Lambda function (like a ParticleLoop kernel) that returns true for the particles which should be in the ParticleSubGroup.

  • args – Arguments in the form of access descriptors wrapping objects to pass to the kernel.

template<typename PARENT>
inline ParticleSubGroupSharedPtr static_particle_sub_group(
std::shared_ptr<PARENT> parent
)#

Create a static ParticleSubGroup which is simply a reference/view into an entire ParticleGroup. This constructor creates a sub-group which is equivalent to 

auto A_all = std::make_shared<ParticleSubGroup>(
  A, [=]() {
return true;
  }
);
but can make additional optimisations.

Parameters:

parent – Parent ParticleGroup or ParticleSubGroup from which to form ParticleSubGroup.

template<typename PARENT, typename INT_TYPE, std::enable_if_t<std::is_integral<INT_TYPE>::value, bool> = true>
inline ParticleSubGroupSharedPtr particle_sub_group(
std::shared_ptr<PARENT> parent,
const INT_TYPE cell,
const bool make_static = false
)#

Create a ParticleSubGroup that selects all particles in a particular cell.

Parameters:

  • parent – Parent ParticleGroup or ParticleSubGroup from which to form ParticleSubGroup.

  • cell – Local cell index to select all particles in.

  • make_static – Make the ParticleSubGroup static (default false).

template<typename PARENT>
inline ParticleSubGroupSharedPtr particle_sub_group(
std::shared_ptr<PARENT> parent,
const int cell,
const bool make_static = false
)#

Create a ParticleSubGroup that selects all particles in a particular cell.

Parameters:

  • parent – Parent ParticleGroup or ParticleSubGroup from which to form ParticleSubGroup.

  • cell – Local cell index to select all particles in.

  • make_static – Make the ParticleSubGroup static (default false).

template<typename PARENT>
inline ParticleSubGroupSharedPtr particle_sub_group(
std::shared_ptr<PARENT> parent,
const int cell_start,
const int cell_end,
const bool make_static = false
)#

Create a ParticleSubGroup that selects all particles in a range of cells.

Parameters:

  • parent – Parent ParticleGroup or ParticleSubGroup from which to form ParticleSubGroup.

  • cell_start – Local cell index to use as the starting cell for a range.

  • cell_end – Local cell index to use as the end cell for a range.

  • make_static – Make the ParticleSubGroup static (default false).

template<typename PARENT>
inline ParticleSubGroupSharedPtr particle_sub_group(
std::shared_ptr<PARENT> parent,
const INT cell,
const bool make_static = false
)#

Create a ParticleSubGroup that selects all particles in a particular cell.

Parameters:

  • parent – Parent ParticleGroup or ParticleSubGroup from which to form ParticleSubGroup.

  • cell – Local cell index to select all particles in.

  • make_static – Make the ParticleSubGroup static (default false).

std::shared_ptr<ParticleSubGroup> particle_sub_group_truncate(
std::shared_ptr<ParticleGroup> particle_group,
const int num_particles,
const bool make_static = false
)#

Create a ParticleSubGroup from a parent by selecting only the first n particles in each cell.

Parameters:

  • particle_group – Particle(Sub)Group which is the parent.

  • num_particles – Number of particles to keep from each cell.

  • make_static – Make the ParticleSubGroup static (default false).

std::shared_ptr<ParticleSubGroup> particle_sub_group_truncate(
std::shared_ptr<ParticleSubGroup> particle_sub_group,
const int num_particles,
const bool make_static = false
)#

Create a ParticleSubGroup from a parent by selecting only the first n particles in each cell.

Parameters:

  • particle_sub_group – Particle(Sub)Group which is the parent.

  • num_particles – Number of particles to keep from each cell.

  • make_static – Make the ParticleSubGroup static (default false).