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	Initialize_inv_size ()
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 (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 BaseParticle *	getFirstBaseParticleInBucket (unsigned int i) const
	Gets the first BaseParticle in the given bucket, const version. More...
BaseParticle *	getFirstBaseParticleInBucket (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 int	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< double >	cellSizes_
	The sizes of the cells in the different grids. More...
std::vector< double >	invCellSizes_
	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< bool >	bucketIsChecked_
	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.

Definition at line 41 of file HGrid.h.

Constructor & Destructor Documentation

HGrid::HGrid

(

)

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

Definition at line 30 of file HGrid.cc.

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

{
    needsRebuilding_ = true;
    numberOfBuckets_ = 10;
    cellOverSizeRatio_ = 1.0;
    occupiedLevelsMask_ = 0;
    logger(DEBUG, "HGrid::HGrid() finished");
}

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

Constructor: initialises parameters and allocates space for internal variables.

Parameters

[in]	num_buckets	The number of buckets that are used by this HGrid.
[in]	cellOverSizeRatio	The maximum ratio between the size of the cell over the size of the particle.
[in]	cellSizes	The sizes of the cells we want to set.

Constructor: initialises parameters and allocates space for internal variables.

Definition at line 47 of file HGrid.cc.

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

{
    needsRebuilding_ = false;
    numberOfBuckets_ = num_buckets;
    cellOverSizeRatio_ = cellOverSizeRatio;
    occupiedLevelsMask_ = 0;
    
    firstBaseParticleInBucket_.resize(numberOfBuckets_, nullptr);
    bucketIsChecked_.resize(numberOfBuckets_, false);

    //std::cout<<"Creating HGrid "<<cellSizes.size()<<" levels:"<<std::endl;
    for (unsigned int i = 0; i < cellSizes.size(); i++)
    {
        //std::cout<<"Level="<<i<<" size="<<cellSizes[i]<<std::endl;
        cellSizes_.push_back(cellSizes[i]);
        invCellSizes_.push_back(1.0 / cellSizes[i]);
    }
    logger(DEBUG, "HGrid::HGrid(unsigned int, double, vector<double>&) constructor finished.");
    /*  std::cout << "HGrid::HGrid(" << num_buckets << ", " << cellOverSizeRatio << ", [";
        for (auto p: cellSizes) std::cout << p << " "; 
        std::cout << "]) finished" << std::endl;*/
}

HGrid::~HGrid

(

)

Destructor.

Definition at line 70 of file HGrid.cc.

References DEBUG, and logger.

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

Member Function Documentation

void HGrid::clearBucketIsChecked

(

)

Sets all buckets to not-checked.

Definition at line 164 of file HGrid.cc.

References bucketIsChecked_.

Referenced by MercuryBase::hGridActionsBeforeTimeStep().

{
    for (std::vector<bool>::iterator it = bucketIsChecked_.begin(); it != bucketIsChecked_.end(); ++it)
    {
        (*it) = false;
    }
}

void HGrid::clearFirstBaseParticleInBucket

(

)

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

Definition at line 188 of file HGrid.cc.

References firstBaseParticleInBucket_.

Referenced by MercuryBase::hGridActionsBeforeTimeStep().

{
    for (std::vector<BaseParticle*>::iterator it = firstBaseParticleInBucket_.begin(); it != firstBaseParticleInBucket_.end(); ++it)
    {
        (*it) = nullptr;
    }
}

unsigned int HGrid::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.

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

Parameters

[in]	x	The coordinate of the cell in x direction for which the hash must be computed.
[in]	y	The coordinate of the cell in y direction for which the hash must be computed.
[in]	z	The coordinate of the cell in z direction for which the hash must be computed.
[in]	l	The 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].

Definition at line 124 of file HGrid.cc.

References numberOfBuckets_.

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

{
    const unsigned int h1 = 0x8da6b343u; // Large multiplicative constants;
    const unsigned int h2 = 0xd8163841u; // here arbitrarily chosen primes
    const unsigned int h3 = 0xcb1ab31fu;
    const unsigned int h4 = 0x165667b1u;
    
    unsigned long int n = h1 * x + h2 * y + h3 * z + h4 * l;
    n = n % numberOfBuckets_;
    
    return static_cast<unsigned int>(n);
}

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]	x	The coordinate of the cell in x direction for which the hash must be computed.
[in]	y	The coordinate of the cell in y direction for which the hash must be computed.
[in]	l	The 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].

Definition at line 144 of file HGrid.cc.

References numberOfBuckets_.

{
    const unsigned int h1 = 0x8da6b343u; // Large multiplicative constants;
    const unsigned int h2 = 0xd8163841u; // here arbitrarily chosen primes
    const unsigned int h4 = 0x165667b1u;
    
    unsigned long int n = h1 * x + h2 * y + h4 * l;
    n = n % numberOfBuckets_;
    
    return static_cast<unsigned int>(n);
}

bool HGrid::getBucketIsChecked

(

unsigned int

i

)

const

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

Parameters

[in]

i

The 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.

Definition at line 200 of file HGrid.cc.

References bucketIsChecked_.

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

{
    return bucketIsChecked_[i];
}

Mdouble HGrid::getCellOverSizeRatio

(

)

const

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.

Definition at line 277 of file HGrid.cc.

References cellOverSizeRatio_.

Referenced by MercuryBase::hGridNeedsRebuilding().

{
    return cellOverSizeRatio_;
}

double HGrid::getCellSize

(

unsigned int

i

)

const

Gets the size of the cells at the given level.

Parameters

[in]

i

The level we want to know the cell size of.

Returns

The size of the cells at the given level.

Definition at line 252 of file HGrid.cc.

References cellSizes_.

Referenced by MercuryBase::hGridUpdateMove().

{
    return cellSizes_[i];
}

const std::vector< double > & HGrid::getCellSizes

(

)

const

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

Returns

A vector with the sizes of the cells of different levels.

Definition at line 175 of file HGrid.cc.

References cellSizes_.

Referenced by MercuryBase::hGridNeedsRebuilding().

{
    return cellSizes_;
}

const BaseParticle * HGrid::getFirstBaseParticleInBucket

(

unsigned int

i

)

const

Gets the first BaseParticle in the given bucket, const version.

Parameters

[in]

i

The 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.

Definition at line 209 of file HGrid.cc.

References firstBaseParticleInBucket_.

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

{
    return firstBaseParticleInBucket_[i];
}

BaseParticle * HGrid::getFirstBaseParticleInBucket

(

unsigned int

i

)

Gets the first BaseParticle in the given bucket.

Parameters

[in]

i

The ordinal number of the bucket for which we want to get the first particle of.

Returns

A pointer to the BaseParticle which is the first Baseparticle in the given bucket.

Definition at line 218 of file HGrid.cc.

References firstBaseParticleInBucket_.

{
    return firstBaseParticleInBucket_[i];
}

double HGrid::getInvCellSize

(

unsigned int

i

)

const

Gets 1/cellSize for the cells on level i.

Parameters

[in]

i

The level we want to know the inverse cell size of.

Returns

The inverse size, i.e. 1/size, of the cells at the given level.

Definition at line 261 of file HGrid.cc.

References invCellSizes_.

Referenced by Mercury2D::hGridFindOneSidedContacts(), Mercury3D::hGridFindOneSidedContacts(), Mercury2D::hGridHasParticleContacts(), Mercury2D::hGridUpdateParticle(), and Mercury3D::hGridUpdateParticle().

{
    return invCellSizes_[i];
}

const std::vector< double > & HGrid::getInvCellSizes

(

)

const

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.

Definition at line 183 of file HGrid.cc.

References invCellSizes_.

{
    return invCellSizes_;
}

bool HGrid::getNeedsRebuilding

(

)

const

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.

Definition at line 269 of file HGrid.cc.

References needsRebuilding_.

Referenced by MercuryBase::hGridNeedsRebuilding().

{
    return needsRebuilding_;
}

unsigned int HGrid::getNumberOfBuckets

(

)

const

Gets the number of buckets of this HGrid.

Returns

The number of buckets in this HGrid.

Definition at line 159 of file HGrid.cc.

References numberOfBuckets_.

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

{
    return numberOfBuckets_;
}

unsigned int HGrid::getNumberOfLevels

(

)

const

Gets the number of levels of this HGrid.

Returns

The number of levels in this HGrid.

Definition at line 234 of file HGrid.cc.

References cellSizes_.

Referenced by Mercury2D::hGridFindOneSidedContacts(), Mercury3D::hGridFindOneSidedContacts(), and Mercury2D::hGridHasParticleContacts().

{
    return cellSizes_.size();
}

int HGrid::getOccupiedLevelsMask

(

)

const

Gets the integer that represents which levels are occupied.

Returns

The integer that represents the bit-vector that indicates which levels have at least one particle.

Definition at line 285 of file HGrid.cc.

References occupiedLevelsMask_.

Referenced by Mercury2D::hGridFindOneSidedContacts(), Mercury3D::hGridFindOneSidedContacts(), and Mercury2D::hGridHasParticleContacts().

{
    return occupiedLevelsMask_;
}

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.

Definition at line 290 of file HGrid.cc.

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

Referenced by MercuryBase::hGridInfo().

{
    std::cout << "Current status of hGrid parameters:" << std::endl;
    std::cout << "bool needsRebuilding_=" << needsRebuilding_ << std::endl; 
    std::cout << "unsigned int numberOfBuckets_=" << numberOfBuckets_ << std::endl; 
    std::cout << "Mdouble cellOverSizeRatio_=" << cellOverSizeRatio_ << std::endl;
    std::cout << "int occupiedLevelsMask_=" << occupiedLevelsMask_ << std::endl; 
    std::cout << "std::vector<double> cellSizes_[" << cellSizes_.size() << "]="; 
    for (auto p: cellSizes_) std::cout << p << " "; 
    std::cout << std::endl; 
    std::cout << "std::vector<double> invCellSizes_[" << invCellSizes_.size() << "]="; 
    for (auto p: invCellSizes_) std::cout << p << " "; 
    std::cout << std::endl; 
    std::cout << "std::vector<BaseParticle> firstBaseParticleInBucket_[" << firstBaseParticleInBucket_.size() << "]=... (not shown)"; 
    //for (auto p: firstBaseParticleInBucket_) std::cout << p << " "; 
    std::cout << std::endl; 
    std::cout << "std::vector<bool> bucketIsChecked_[" << bucketIsChecked_.size() << "]=... (not shown)"; 
    //for (auto p: bucketIsChecked_) std::cout << p << " "; 
    std::cout << std::endl; 
}

void HGrid::Initialize_inv_size

(

)

Todo:

TW: Where is this function defined??

void HGrid::insertParticleToHgrid

(

BaseParticle *

obj

)

Inserts the given BaseParticle in to the HGrid.

Parameters

[in]

obj

A 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.

Definition at line 88 of file HGrid.cc.

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

Referenced by MercuryBase::hGridInsertParticle().

{
    if(!needsRebuilding_)
    {
        // Find lowest level where object fully fits inside cell, taking cellOverSizeRatio_ into account
        Mdouble diameter = obj->getInteractionRadius() * 2.0;
        unsigned int level = 0;
        while (level < cellSizes_.size() && cellSizes_[level] <= diameter * cellOverSizeRatio_)
        {
            level++;
        }

        if (level >= cellSizes_.size())
        {
            logger(WARN, "WARNING: object (id = %, index = %) is larger (d = %, cellOverSizeRatio = %) than largest grid cell (%) allows.", obj->getId(), obj->getIndex(), diameter, cellOverSizeRatio_, cellSizes_.back());
            needsRebuilding_ = true;
        }

        obj->setHGridLevel(level);
        // indicate level is in use - not levels with no particles no collision detection is performed
        this->occupiedLevelsMask_ |= (1 << level);
    }
    else
    {
        logger(WARN, "WARNING: the HGrid needs to be rebuild before insertParticleToHgrid may be called!");
    }
}

void HGrid::setBucketIsChecked

(

unsigned int

i

)

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

Parameters

[in]

i

The ordinal number of the bucket we want to mark as checked.

Definition at line 226 of file HGrid.cc.

References bucketIsChecked_.

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

{
    bucketIsChecked_[i] = true;
}

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

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

Parameters

[in]	i	The ordinal number of the bucket we want to set the first BaseParticle for.
[in]	p	A pointer to the BaseParticle we want to place in the given bucket.

Definition at line 243 of file HGrid.cc.

References firstBaseParticleInBucket_.

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

{
    firstBaseParticleInBucket_[i] = p;
}

Member Data Documentation

std::vector<bool> HGrid::bucketIsChecked_

private

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

Definition at line 216 of file HGrid.h.

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

Mdouble HGrid::cellOverSizeRatio_

private

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

Definition at line 183 of file HGrid.h.

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

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.

Definition at line 198 of file HGrid.h.

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

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.

Definition at line 211 of file HGrid.h.

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

std::vector<double> HGrid::invCellSizes_

private

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

Definition at line 203 of file HGrid.h.

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

bool HGrid::needsRebuilding_

private

Flag sets if the HGrid needs to be rebuilt.

Definition at line 171 of file HGrid.h.

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

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.

Definition at line 178 of file HGrid.h.

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

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.

Definition at line 190 of file HGrid.h.

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

---

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

• HGrid.h
• HGrid.cc