Cell-Lists

Cell-lists are used to map from space to particles and vice-versa.

Internal structure

A cell list is composed of:

  1. The representation of the cells geometry (here a uniform grid): see mirheo::CellListInfo
  2. Number of particles per cell
  3. Index of the first particle in each cell
  4. The particle data, reordered to match the above structure.

API

class CellListInfo

A device-compatible structure that represents the cell-lists structure.

Contains geometric info (number of cells, cell sizes) and associated particles info (number of particles per cell and cell-starts).

Subclassed by mirheo::CellList

Public Functions

CellListInfo(real3 h, real3 localDomainSize)

Construct a CellListInfo object.

This will create a cell-lists structure with cell sizes which are larger or equal to

h, such that the number of cells fit exactly inside the local domain size.
Parameters
  • h: The size of a single cell along each dimension
  • localDomainSize: Size of the local domain

CellListInfo(real rc, real3 localDomainSize)

Construct a CellListInfo object.

This will create a cell-lists structure with cell sizes which are larger or equal to

rc, such that the number of cells fit exactly inside the local domain size.
Parameters
  • rc: The minimum size of a single cell along every dimension
  • localDomainSize: Size of the local domain

__device__ __host__ int encode(int ix, int iy, int iz) const

map 3D cell indices to linear cell index.

Return
Linear cell index
Parameters
  • ix: Cell index in the x direction
  • iy: Cell index in the y direction
  • iz: Cell index in the z direction

__device__ __host__ void decode(int cid, int &ix, int &iy, int &iz) const

map linear cell index to 3D cell indices.

Parameters
  • cid: Linear cell index
  • ix: Cell index in the x direction
  • iy: Cell index in the y direction
  • iz: Cell index in the z direction

__device__ __host__ int encode(int3 cid3) const

see encode()

__device__ __host__ int3 decode(int cid) const

see decode()

template <CellListsProjection Projection = CellListsProjection::Clamp>
__device__ __host__ int3 getCellIdAlongAxes(const real3 x) const

Map from position to cell indices.

Return
cell indices
Template Parameters
  • Projection: if the cell indices must be clamped or not
Parameters
  • x: The position in local coordinates

template <CellListsProjection Projection = CellListsProjection::Clamp, typename T>
__device__ __host__ int getCellId(const T x) const

Map from position to linear indices.

Warning

If The projection is set to CellListsProjection::NoClamp, this function will return -1 if the particle is outside the subdomain.

Return
linear cell index
Template Parameters
  • Projection: if the cell indices must be clamped or not
  • T: The vector type that represents the position
Parameters
  • x: The position in local coordinates

Public Members

int3 ncells

Number of cells along each direction in the local domain.

int totcells

total number of cells in the local domain

real3 localDomainSize

dimensions of the subdomain

real rc

cutoff radius

real3 h

dimensions of the cells along each direction

int *cellSizes = {nullptr}

number of particles contained in each cell

int *cellStarts = {nullptr}

exclusive prefix sum of cellSizes

int *order = {nullptr}

used to reorder particles when building the cell lists: order[pid] is the destination index of the particle with index pid before reordering

class CellList : public mirheo::CellListInfo

Contains the cell-list data for a given ParticleVector.

As opposed to the PrimaryCellList class, it contains a copy of the attached ParticleVector. This means that the original ParticleVector data will not be reorder but rather copied into this container. This is useful when several CellList object can be attached to the same ParticleVector or if the ParticleVector must not be reordered such as e.g. for ObjectVector objects.

Subclassed by mirheo::PrimaryCellList

Public Functions

CellList(ParticleVector *pv, real rc, real3 localDomainSize)

Construct a CellList object.

Parameters
  • pv: The ParticleVector to attach.
  • rc: The maximum cut-off radius that can be used with that cell list.
  • localDomainSize: The size of the local subdomain

CellList(ParticleVector *pv, int3 resolution, real3 localDomainSize)

Construct a CellList object.

Parameters
  • pv: The ParticleVector to attach.
  • resolution: The number of cells along each dimension
  • localDomainSize: The size of the local subdomain

CellListInfo cellInfo()

Return
the device-compatible handler

virtual void build(cudaStream_t stream)

construct the cell-list associated with the attached ParticleVector

Parameters
  • stream: The stream used to execute the process

virtual void accumulateChannels(const std::vector<std::string> &channelNames, cudaStream_t stream)

Accumulate the channels from the data contained inside the cell-list container to the attached ParticleVector.

Parameters
  • channelNames: List that contains the names of all the channels to accumulate
  • stream: Execution stream

virtual void gatherChannels(const std::vector<std::string> &channelNames, cudaStream_t stream)

Copy the channels from the attached ParticleVector to the cell-lists data.

Parameters
  • channelNames: List that contains the names of all the channels to copy
  • stream: Execution stream

void clearChannels(const std::vector<std::string> &channelNames, cudaStream_t stream)

Clear channels contained inside the cell-list.

Parameters
  • channelNames: List that contains the names of all the channels to clear
  • stream: Execution stream

template <typename ViewType>
ViewType getView() const

Create a view that points to the data contained in the cell-lists.

Return
View that points to the cell-lists data
Template Parameters
  • ViewType: The type of the view to create

template <typename T>
void requireExtraDataPerParticle(const std::string &name)

Add an extra channel to the cell-list.

Template Parameters
  • T: The type of data to add
Parameters
  • name: Name of the channel

LocalParticleVector *getLocalParticleVector()

Return
The LocalParticleVector that contains the data in the cell-list

class PrimaryCellList : public mirheo::CellList

Contains the cell-list map for a given ParticleVector.

As opposed to the CellList class, the data is stored only in the ParticleVector. This means that the original ParticleVector data will be reorder according to this cell-list. This allows to save memory and avoid extra copies. On the other hand, this class must not be used with ObjectVector objects.

Public Functions

PrimaryCellList(ParticleVector *pv, real rc, real3 localDomainSize)

Construct a PrimaryCellList object.

Parameters
  • pv: The ParticleVector to attach.
  • rc: The maximum cut-off radius that can be used with that cell list.
  • localDomainSize: The size of the local subdomain

PrimaryCellList(ParticleVector *pv, int3 resolution, real3 localDomainSize)

Construct a PrimaryCellList object.

Parameters
  • pv: The ParticleVector to attach.
  • resolution: The number of cells along each dimension
  • localDomainSize: The size of the local subdomain

void build(cudaStream_t stream)

construct the cell-list associated with the attached ParticleVector

Parameters
  • stream: The stream used to execute the process

void accumulateChannels(const std::vector<std::string> &channelNames, cudaStream_t stream)

Accumulate the channels from the data contained inside the cell-list container to the attached ParticleVector.

Parameters
  • channelNames: List that contains the names of all the channels to accumulate
  • stream: Execution stream

void gatherChannels(const std::vector<std::string> &channelNames, cudaStream_t stream)

Copy the channels from the attached ParticleVector to the cell-lists data.

Parameters
  • channelNames: List that contains the names of all the channels to copy
  • stream: Execution stream