HGrid Class Reference

In the HGrid class, here all information about the HGrid is stored. More...

#include <HGrid.h>

Public Member Functions

 HGrid ()
 Default constructor, it sets the parameters to some sensible defaults. More...
 
 HGrid (unsigned int num_buckets, double cellOverSizeRatio, std::vector< double > &cellSizes)
 Constructor: initialises parameters and allocates space for internal variables. More...
 
 ~HGrid ()
 Destructor. More...
 
void insertParticleToHgrid (BaseParticle *obj)
 Inserts the given BaseParticle in to the HGrid. More...
 
unsigned int computeHashBucketIndex (int x, int y, int z, unsigned int l) const
 Computes hash bucket index in range [0, NUM_BUCKETS-1] for a 3D domain. More...
 
unsigned int computeHashBucketIndex (HGridCell hGridCell) const
 Computes hash bucket index in range [0, NUM_BUCKETS-1] for a 3D domain. More...
 
unsigned int computeHashBucketIndex (int x, int y, unsigned int l) const
 Computes hash bucket index in range [0, NUM_BUCKETS-1] for a 2D domain. More...
 
void clearBucketIsChecked ()
 Sets all buckets to not-checked. More...
 
void clearFirstBaseParticleInBucket ()
 For all buckets, it removes the pointer to the first BaseParticle in it, practically emptying the buckets. More...
 
void setFirstBaseParticleInBucket (unsigned int i, BaseParticle *p)
 Sets the first particle in bucket i to be the given BaseParticle. More...
 
void setBucketIsChecked (unsigned int i)
 Sets that the bucket with the given index is checked to true. More...
 
bool getBucketIsChecked (unsigned int i) const
 Gets whether or not the bucket with index i is checked. More...
 
Mdouble getCellOverSizeRatio () const
 Gets the maximum ratio of the cell to a particle it contains. More...
 
double getCellSize (unsigned int i) const
 Gets the size of the cells at the given level. More...
 
const std::vector< double > & getCellSizes () const
 Gets the sizes of the cells at all levels as a vector. More...
 
const BaseParticlegetFirstBaseParticleInBucket (unsigned int i) const
 Gets the first BaseParticle in the given bucket, const version. More...
 
BaseParticlegetFirstBaseParticleInBucket (unsigned int i)
 Gets the first BaseParticle in the given bucket. More...
 
double getInvCellSize (unsigned int i) const
 Gets 1/cellSize for the cells on level i. More...
 
const std::vector< double > & getInvCellSizes () const
 Gets all the inverse cell sizes (1/cellSize) for all levels as a vector. More...
 
bool getNeedsRebuilding () const
 Gets whether or not the grid needs to be rebuilt before something else is done with it. More...
 
unsigned int getNumberOfBuckets () const
 Gets the number of buckets of this HGrid. More...
 
unsigned long getNumberOfLevels () const
 Gets the number of levels of this HGrid. More...
 
int getOccupiedLevelsMask () const
 Gets the integer that represents which levels are occupied. More...
 
void info () const
 Displays the member variables of the hGrid object. This function is intended for debugging the hGrid, therefore the variables are displayed next to the variable names instead of putting it in a user-friendly format. More...
 

Private Attributes

bool needsRebuilding_
 Flag sets if the HGrid needs to be rebuilt. More...
 
unsigned int numberOfBuckets_
 The number of buckets in the current HGrid. More...
 
Mdouble cellOverSizeRatio_
 The maximum ratio between the size of the cell and the size of a particle it contains. More...
 
int occupiedLevelsMask_
 Marks if there are particles at certain levels. More...
 
std::vector< doublecellSizes_
 The sizes of the cells in the different grids. More...
 
std::vector< doubleinvCellSizes_
 The inverse sizes of the cells in the different grids, where the inverse is defined as 1/cellSizes_. More...
 
std::vector< BaseParticle * > firstBaseParticleInBucket_
 Stores a pointer to first element in hash bucket b. More...
 
std::vector< boolbucketIsChecked_
 BucketIsChecked stores if hash bucket b is checked already; initially all false. More...
 

Detailed Description

In the HGrid class, here all information about the HGrid is stored.

In particular, the hashing the grid is done in this class, the cell sizes of the different levels are stored, it is stored whether or not there are BaseParticle on each level and there is a flag to see if the HGrid needs to be rebuilt.

Constructor & Destructor Documentation

◆ HGrid() [1/2]

HGrid::HGrid ( )

Default constructor, it sets the parameters to some sensible defaults.

31 {
32  needsRebuilding_ = true;
33  numberOfBuckets_ = 10;
34  cellOverSizeRatio_ = 1.0;
36  logger(DEBUG, "HGrid::HGrid() finished");
37 }
Logger< MERCURYDPM_LOGLEVEL > logger("MercuryKernel")
Definition of different loggers with certain modules. A user can define its own custom logger here.
@ DEBUG
bool needsRebuilding_
Flag sets if the HGrid needs to be rebuilt.
Definition: HGrid.h:228
Mdouble cellOverSizeRatio_
The maximum ratio between the size of the cell and the size of a particle it contains.
Definition: HGrid.h:240
unsigned int numberOfBuckets_
The number of buckets in the current HGrid.
Definition: HGrid.h:235
int occupiedLevelsMask_
Marks if there are particles at certain levels.
Definition: HGrid.h:247

References cellOverSizeRatio_, DEBUG, logger, needsRebuilding_, numberOfBuckets_, and occupiedLevelsMask_.

◆ HGrid() [2/2]

HGrid::HGrid ( unsigned int  num_buckets,
double  cellOverSizeRatio,
std::vector< double > &  cellSizes 
)

Constructor: initialises parameters and allocates space for internal variables.

Parameters
[in]num_bucketsThe number of buckets that are used by this HGrid.
[in]cellOverSizeRatioThe maximum ratio between the size of the cell over the size of the particle.
[in]cellSizesThe sizes of the cells we want to set.

Constructor: initialises parameters and allocates space for internal variables.

48 {
49  needsRebuilding_ = false;
50  numberOfBuckets_ = num_buckets;
51  cellOverSizeRatio_ = cellOverSizeRatio;
53  invCellSizes_ = std::vector<double>(0);
54 
56  bucketIsChecked_.resize(numberOfBuckets_, false);
57 
58  //std::cout<<"Creating HGrid "<<cellSizes.size()<<" levels:"<<std::endl;
59  for (double cellSize : cellSizes)
60  {
61  //std::cout<<"Level="<<i<<" size="<<cellSizes[i]<<std::endl;
62  cellSizes_.push_back(cellSize);
63  invCellSizes_.push_back(1.0 / cellSize);
64  }
65  logger(DEBUG, "HGrid::HGrid(unsigned int, double, vector<double>&) constructor finished.");
66  /* std::cout << "HGrid::HGrid(" << num_buckets << ", " << cellOverSizeRatio << ", [";
67  for (auto p: cellSizes) std::cout << p << " ";
68  std::cout << "]) finished" << std::endl;*/
69 }
std::vector< bool > bucketIsChecked_
BucketIsChecked stores if hash bucket b is checked already; initially all false.
Definition: HGrid.h:273
std::vector< double > invCellSizes_
The inverse sizes of the cells in the different grids, where the inverse is defined as 1/cellSizes_.
Definition: HGrid.h:260
std::vector< double > cellSizes_
The sizes of the cells in the different grids.
Definition: HGrid.h:255
std::vector< BaseParticle * > firstBaseParticleInBucket_
Stores a pointer to first element in hash bucket b.
Definition: HGrid.h:268

References bucketIsChecked_, cellOverSizeRatio_, cellSizes_, DEBUG, firstBaseParticleInBucket_, invCellSizes_, logger, needsRebuilding_, numberOfBuckets_, and occupiedLevelsMask_.

◆ ~HGrid()

HGrid::~HGrid ( )

Destructor.

72 {
73  logger(DEBUG, "HGrid::~HGrid() destructor finished");
74 }

References DEBUG, and logger.

Member Function Documentation

◆ clearBucketIsChecked()

void HGrid::clearBucketIsChecked ( )

Sets all buckets to not-checked.

141 {
142  std::fill(bucketIsChecked_.begin(), bucketIsChecked_.end(), false);
143 }

References bucketIsChecked_.

Referenced by MercuryBase::hGridActionsBeforeTimeStep().

◆ clearFirstBaseParticleInBucket()

void HGrid::clearFirstBaseParticleInBucket ( )

For all buckets, it removes the pointer to the first BaseParticle in it, practically emptying the buckets.

146 {
147  std::fill(firstBaseParticleInBucket_.begin(), firstBaseParticleInBucket_.end(), nullptr);
148 }

References firstBaseParticleInBucket_.

Referenced by MercuryBase::hGridActionsBeforeTimeStep().

◆ computeHashBucketIndex() [1/3]

unsigned int HGrid::computeHashBucketIndex ( HGridCell  hGridCell) const
inline

Computes hash bucket index in range [0, NUM_BUCKETS-1] for a 3D domain.

90  {
91  return computeHashBucketIndex(hGridCell.getHGridX(),
92  hGridCell.getHGridY(),
93  hGridCell.getHGridZ(),
94  hGridCell.getHGridLevel());
95  }
unsigned int getHGridLevel() const
Definition: HGridCell.h:86
int getHGridX() const
Definition: HGridCell.h:56
int getHGridZ() const
Definition: HGridCell.h:76
int getHGridY() const
Definition: HGridCell.h:66
unsigned int computeHashBucketIndex(int x, int y, int z, unsigned int l) const
Computes hash bucket index in range [0, NUM_BUCKETS-1] for a 3D domain.
Definition: HGrid.h:76

References computeHashBucketIndex(), HGridCell::getHGridLevel(), HGridCell::getHGridX(), HGridCell::getHGridY(), and HGridCell::getHGridZ().

◆ computeHashBucketIndex() [2/3]

unsigned int HGrid::computeHashBucketIndex ( int  x,
int  y,
int  z,
unsigned int  l 
) const
inline

Computes hash bucket index in range [0, NUM_BUCKETS-1] for a 3D domain.

Computes a hash from parameters, the result is in range [0, numberOfBuckets_-1]. Inline for performance reasons: this method is called VERY often.

Parameters
[in]xThe coordinate of the cell in x direction for which the hash must be computed.
[in]yThe coordinate of the cell in y direction for which the hash must be computed.
[in]zThe coordinate of the cell in z direction for which the hash must be computed.
[in]lThe level in the HGrid of the cell for which the hash must be computed.
Returns
The hash value for the given cell (x,y,z,l), which is in the range [0,numberOfBuckets_-1].
Todo:
consider moving to HGridCell, which might give better performance.
77  {
78  static const unsigned int h1 = 0x8da6b343u; // Large multiplicative constants;
79  static const unsigned int h2 = 0xd8163841u; // here arbitrarily chosen primes
80  static const unsigned int h3 = 0xcb1ab31fu;
81  static const unsigned int h4 = 0x165667b1u;
82 
83  return (h1 * x + h2 * y + h3 * z + h4 * l) % numberOfBuckets_;
84  }

References numberOfBuckets_.

Referenced by computeHashBucketIndex(), DPM::computeLocalCGHGrid(), DPM::computeLocalVolumeFractionHGrid(), Mercury3D::computeWallForces(), Mercury3D::hGridFindContactsWithinTargetCell(), Mercury2D::hGridFindContactsWithinTargetCell(), Mercury3D::hGridFindContactsWithTargetCell(), Mercury2D::hGridFindContactsWithTargetCell(), Mercury2D::hGridFindParticleContacts(), Mercury3D::hGridFindParticleContacts(), Mercury3D::hGridFindParticlesWithTargetCell(), Mercury2D::hGridFindParticlesWithTargetCell(), Mercury3D::hGridHasContactsInTargetCell(), Mercury2D::hGridHasContactsInTargetCell(), Mercury2D::hGridRemoveParticle(), Mercury3D::hGridRemoveParticle(), Mercury2D::hGridUpdateParticle(), and Mercury3D::hGridUpdateParticle().

◆ computeHashBucketIndex() [3/3]

unsigned int HGrid::computeHashBucketIndex ( int  x,
int  y,
unsigned int  l 
) const

Computes hash bucket index in range [0, NUM_BUCKETS-1] for a 2D domain.

Computes a hash from parameters, the result is in range [0, numberOfBuckets_-1].

Parameters
[in]xThe coordinate of the cell in x direction for which the hash must be computed.
[in]yThe coordinate of the cell in y direction for which the hash must be computed.
[in]lThe level in the HGrid of the cell for which the hash must be computed.
Returns
The hash value for the given cell (x,y,l), which is in the range [0,numberOfBuckets_-1].
128 {
129  const unsigned int h1 = 0x8da6b343u; // Large multiplicative constants;
130  const unsigned int h2 = 0xd8163841u; // here arbitrarily chosen primes
131  const unsigned int h4 = 0x165667b1u;
132 
133  unsigned long int n = h1 * x + h2 * y + h4 * l;
134  n = n % numberOfBuckets_;
135 
136  return static_cast<unsigned int>(n);
137 }
const unsigned n
Definition: CG3DPackingUnitTest.cpp:32

References n, and numberOfBuckets_.

◆ getBucketIsChecked()

bool HGrid::getBucketIsChecked ( unsigned int  i) const
inline

Gets whether or not the bucket with index i is checked.

Parameters
[in]iThe ordinal number of the bucket we want to know for whether or not it has been checked.
Returns
A boolean which is true if the bucket is checked and false otherwise.
133  { return bucketIsChecked_[i]; }
const std::complex< Mdouble > i
Definition: ExtendedMath.h:51

References bucketIsChecked_, and constants::i.

Referenced by Mercury3D::hGridFindContactsWithinTargetCell(), and Mercury2D::hGridFindContactsWithinTargetCell().

◆ getCellOverSizeRatio()

Mdouble HGrid::getCellOverSizeRatio ( ) const
inline

Gets the maximum ratio of the cell to a particle it contains.

Returns
The ratio between the size of the smallest cell and the smallest BaseParticle.
140  { return cellOverSizeRatio_; }

References cellOverSizeRatio_.

Referenced by MercuryBase::hGridNeedsRebuilding().

◆ getCellSize()

double HGrid::getCellSize ( unsigned int  i) const
inline

Gets the size of the cells at the given level.

Parameters
[in]iThe level we want to know the cell size of.
Returns
The size of the cells at the given level.
148  { return cellSizes_[i]; }

References cellSizes_, and constants::i.

◆ getCellSizes()

const std::vector<double>& HGrid::getCellSizes ( ) const
inline

Gets the sizes of the cells at all levels as a vector.

Returns
A vector with the sizes of the cells of different levels.
155  { return cellSizes_; }

References cellSizes_.

Referenced by MercuryBase::hGridInfo(), and MercuryBase::hGridNeedsRebuilding().

◆ getFirstBaseParticleInBucket() [1/2]

BaseParticle* HGrid::getFirstBaseParticleInBucket ( unsigned int  i)
inline

Gets the first BaseParticle in the given bucket.

Parameters
[in]iThe ordinal number of the bucket for which we want to get the first particle of.
Returns
A pointer to the (constant) BaseParticle which is the first Baseparticle in the given bucket.
171  { return firstBaseParticleInBucket_[i]; }

References firstBaseParticleInBucket_, and constants::i.

◆ getFirstBaseParticleInBucket() [2/2]

◆ getInvCellSize()

◆ getInvCellSizes()

const std::vector<double>& HGrid::getInvCellSizes ( ) const
inline

Gets all the inverse cell sizes (1/cellSize) for all levels as a vector.

Returns
A vector with the inverse sizes (1/size) of the cells of different levels.
186  { return invCellSizes_; }

References invCellSizes_.

◆ getNeedsRebuilding()

bool HGrid::getNeedsRebuilding ( ) const
inline

Gets whether or not the grid needs to be rebuilt before something else is done with it.

Returns
A boolean which indicates whether or not the HGrid needs rebuilding.
193  { return needsRebuilding_; }

References needsRebuilding_.

Referenced by MercuryBase::hGridNeedsRebuilding().

◆ getNumberOfBuckets()

unsigned int HGrid::getNumberOfBuckets ( ) const
inline

Gets the number of buckets of this HGrid.

Returns
The number of buckets in this HGrid.
200  { return numberOfBuckets_; }

References numberOfBuckets_.

Referenced by MercuryBase::hGridInfo(), and MercuryBase::hGridNeedsRebuilding().

◆ getNumberOfLevels()

◆ getOccupiedLevelsMask()

◆ info()

void HGrid::info ( ) const

Displays the member variables of the hGrid object. This function is intended for debugging the hGrid, therefore the variables are displayed next to the variable names instead of putting it in a user-friendly format.

Todo:
use logger everywhere
152 {
153  logger(INFO, " numberOfBuckets %\n", Flusher::NO_FLUSH, numberOfBuckets_);
154  logger(INFO, " cellOverSizeRatio %\n", Flusher::NO_FLUSH, cellOverSizeRatio_);
155  logger(INFO, " cellSizes\n", Flusher::NO_FLUSH);
156  for (auto p: cellSizes_)
157  {
158  logger(INFO, " %\n", p, Flusher::NO_FLUSH);
159  }
160  logger(INFO, "");
161 }
@ INFO

References cellOverSizeRatio_, cellSizes_, INFO, logger, NO_FLUSH, and numberOfBuckets_.

Referenced by EllipsoidsBouncingOnWallDemo::actionsAfterSolve(), EllipticalSuperQuadricCollision::actionsAfterSolve(), SphericalSuperQuadricCollision::actionsAfterSolve(), and VisualisationTest::actionsAfterSolve().

◆ insertParticleToHgrid()

void HGrid::insertParticleToHgrid ( BaseParticle obj)

Inserts the given BaseParticle in to the HGrid.

Parameters
[in]objA pointer to the BaseParticle we want to add to the HGrid.

Inserts the given BaseParticle into the HGrid, i.e. it sets up the particle grid properties and updates the level information on the grid. First find which level is big enough to fit the BaseParticle in, then add the BaseParticle to that level and set that level as occupied in the occupiedLevelsMask_.

Bug:
What happens if the particle is too big for the biggest cell? It just says that it needs to rebuild the HGrid, but the particle is not inserted and there seems to be no indication to the rest of the code that it has not been inserted. For now giving a warning, since code of users may rely on it that nothing happens.
90 {
91  if (!needsRebuilding_)
92  {
93  // Find lowest level where object fully fits inside cell, taking cellOverSizeRatio_ into account
94  Mdouble diameter = obj->getMaxInteractionRadius() * 2.0;
95  unsigned int level = 0;
96  while (level <= (cellSizes_.size() - 1) && cellSizes_[level] <= diameter * cellOverSizeRatio_)
97  {
98  level++;
99  }
100 
101  //Check if the size of the particle is larger than the required grid
102  if (level >= cellSizes_.size())
103  {
104  logger(WARN, "WARNING: object (id = %, index = %) is larger (d = %, cellOverSizeRatio = %) than largest "
105  "grid cell (%) allows.",
106  obj->getId(), obj->getIndex(), diameter, cellOverSizeRatio_, cellSizes_.back());
107  needsRebuilding_ = true;
108  }
109 
110  obj->setHGridLevel(level);
111  // indicate level is in use - not levels with no particles no collision detection is performed
112  this->occupiedLevelsMask_ |= (1 << level);
113  }
114  else
115  {
116  logger(WARN, "WARNING: the HGrid needs to be rebuilt before insertParticleToHgrid may be called!");
117  }
118 }
double Mdouble
Definition: GeneralDefine.h:34
@ WARN
unsigned int getId() const
Returns the unique identifier of any particular object.
Definition: BaseObject.h:125
unsigned int getIndex() const
Returns the index of the object in the handler.
Definition: BaseObject.h:118
void setHGridLevel(const unsigned int level)
Sets the particle's HGrid level.
Definition: BaseParticle.h:472
Mdouble getMaxInteractionRadius() const
Returns the particle's interaction radius, which might be different from radius_ (e....
Definition: BaseParticle.h:362

References cellOverSizeRatio_, cellSizes_, BaseObject::getId(), BaseObject::getIndex(), BaseParticle::getMaxInteractionRadius(), logger, needsRebuilding_, occupiedLevelsMask_, BaseParticle::setHGridLevel(), and WARN.

Referenced by MercuryBase::hGridInsertParticle().

◆ setBucketIsChecked()

void HGrid::setBucketIsChecked ( unsigned int  i)
inline

Sets that the bucket with the given index is checked to true.

Parameters
[in]iThe ordinal number of the bucket we want to mark as checked.
125  { bucketIsChecked_[i] = true; }

References bucketIsChecked_, and constants::i.

Referenced by Mercury3D::hGridFindContactsWithinTargetCell(), and Mercury2D::hGridFindContactsWithinTargetCell().

◆ setFirstBaseParticleInBucket()

void HGrid::setFirstBaseParticleInBucket ( unsigned int  i,
BaseParticle p 
)
inline

Sets the first particle in bucket i to be the given BaseParticle.

Parameters
[in]iThe ordinal number of the bucket we want to set the first BaseParticle for.
[in]pA pointer to the BaseParticle we want to place in the given bucket.
118  { firstBaseParticleInBucket_[i] = p; }

References firstBaseParticleInBucket_, and constants::i.

Referenced by Mercury2D::hGridRemoveParticle(), Mercury3D::hGridRemoveParticle(), Mercury2D::hGridUpdateParticle(), and Mercury3D::hGridUpdateParticle().

Member Data Documentation

◆ bucketIsChecked_

std::vector<bool> HGrid::bucketIsChecked_
private

BucketIsChecked stores if hash bucket b is checked already; initially all false.

Referenced by clearBucketIsChecked(), getBucketIsChecked(), HGrid(), and setBucketIsChecked().

◆ cellOverSizeRatio_

Mdouble HGrid::cellOverSizeRatio_
private

The maximum ratio between the size of the cell and the size of a particle it contains.

Referenced by getCellOverSizeRatio(), HGrid(), info(), and insertParticleToHgrid().

◆ cellSizes_

std::vector<double> HGrid::cellSizes_
private

The sizes of the cells in the different grids.

The sizes of the cells in the different grids are saved in a vector of double. The smaller the index in the vector, the smaller the cells.

Referenced by getCellSize(), getCellSizes(), getNumberOfLevels(), HGrid(), info(), and insertParticleToHgrid().

◆ firstBaseParticleInBucket_

std::vector<BaseParticle*> HGrid::firstBaseParticleInBucket_
private

Stores a pointer to first element in hash bucket b.

The pointer to the first element in a certain bucket, initially a nullptr, is the pointer to the first BaseParticle in the first cell in the bucket.

Referenced by clearFirstBaseParticleInBucket(), getFirstBaseParticleInBucket(), HGrid(), and setFirstBaseParticleInBucket().

◆ invCellSizes_

std::vector<double> HGrid::invCellSizes_
private

The inverse sizes of the cells in the different grids, where the inverse is defined as 1/cellSizes_.

Referenced by getInvCellSize(), getInvCellSizes(), and HGrid().

◆ needsRebuilding_

bool HGrid::needsRebuilding_
private

Flag sets if the HGrid needs to be rebuilt.

Referenced by getNeedsRebuilding(), HGrid(), and insertParticleToHgrid().

◆ numberOfBuckets_

unsigned int HGrid::numberOfBuckets_
private

The number of buckets in the current HGrid.

The number of buckets is the number of possible "results" of the hash function for the grid.

Referenced by computeHashBucketIndex(), getNumberOfBuckets(), HGrid(), and info().

◆ occupiedLevelsMask_

int HGrid::occupiedLevelsMask_
private

Marks if there are particles at certain levels.

The l-th bit of occupiedLevelsMask_ is 1 if level l is contains particles (Implies max 32 hgrid levels) and 0 if it contains none.

Referenced by getOccupiedLevelsMask(), HGrid(), and insertParticleToHgrid().


The documentation for this class was generated from the following files: