#include <DistributedBoxCollection.hpp>

Inheritance diagram for DistributedBoxCollection< DIM >:

Collaboration diagram for DistributedBoxCollection< DIM >:

Public Member Functions
	DistributedBoxCollection (double boxWidth, c_vector< double, 2 *DIM > domainSize, bool isPeriodicInX=false, bool isPeriodicInY=false, bool isPeriodicInZ=false, int localRows=PETSC_DECIDE)

	~DistributedBoxCollection ()

void	EmptyBoxes ()

void	UpdateHaloBoxes ()

unsigned	GetNumLocalRows () const

bool	IsBoxOwned (unsigned globalIndex)

bool	IsInteriorBox (unsigned globalIndex)

bool	IsHaloBox (unsigned globalIndex)

unsigned	CalculateGlobalIndex (c_vector< unsigned, DIM > gridIndices)

unsigned	CalculateContainingBox (Node< DIM > *pNode)

unsigned	CalculateContainingBox (c_vector< double, DIM > &rLocation)

c_vector< unsigned, DIM >	CalculateGridIndices (unsigned globalIndex)

Box< DIM > &	rGetBox (unsigned boxIndex)

Box< DIM > &	rGetHaloBox (unsigned boxIndex)

unsigned	GetNumBoxes ()

unsigned	GetNumLocalBoxes ()

c_vector< double, 2 *DIM >	rGetDomainSize () const

bool	GetAreLocalBoxesSet () const

double	GetBoxWidth () const

bool	GetIsPeriodicInX () const

bool	GetIsPeriodicInY () const

bool	GetIsPeriodicInZ () const

bool	GetIsPeriodicAcrossProcs () const

c_vector< bool, DIM >	GetIsPeriodicAllDims () const

unsigned	GetNumRowsOfBoxes () const

int	LoadBalance (std::vector< int > localDistribution)

void	SetupLocalBoxesHalfOnly ()

void	SetupAllLocalBoxes ()

std::set< unsigned > &	rGetLocalBoxes (unsigned boxIndex)

bool	IsOwned (Node< DIM > *pNode)

bool	IsOwned (c_vector< double, DIM > &location)

unsigned	GetProcessOwningNode (Node< DIM > *pNode)

std::vector< unsigned > &	rGetHaloNodesRight ()

std::vector< unsigned > &	rGetHaloNodesLeft ()

void	SetCalculateNodeNeighbours (bool calculateNodeNeighbours)

void	CalculateNodePairs (std::vector< Node< DIM > * > &rNodes, std::vector< std::pair< Node< DIM > , Node< DIM > > > &rNodePairs)

void	CalculateInteriorNodePairs (std::vector< Node< DIM > * > &rNodes, std::vector< std::pair< Node< DIM > , Node< DIM > > > &rNodePairs)

void	CalculateBoundaryNodePairs (std::vector< Node< DIM > * > &rNodes, std::vector< std::pair< Node< DIM > , Node< DIM > > > &rNodePairs)

void	AddPairsFromBox (unsigned boxIndex, std::vector< std::pair< Node< DIM > , Node< DIM > > > &rNodePairs)

std::vector< int >	CalculateNumberOfNodesInEachStrip ()

Private Member Functions
void	SetupHaloBoxes ()

template<class Archive >
void	serialize (Archive &archive, const unsigned int version)

Private Attributes
std::vector< Box< DIM > >	mBoxes

std::vector< Box< DIM > >	mHaloBoxes

std::vector< unsigned >	mHalosRight

std::vector< unsigned >	mHalosLeft

std::vector< unsigned >	mHaloNodesRight

std::vector< unsigned >	mHaloNodesLeft

std::map< unsigned, unsigned >	mHaloBoxesMapping

c_vector< double, 2 *DIM >	mDomainSize

double	mBoxWidth

unsigned	mNumBoxes

c_vector< unsigned, DIM >	mNumBoxesEachDirection

unsigned	mNumBoxesInAFace

std::vector< std::set< unsigned > >	mLocalBoxes

unsigned	mMinBoxIndex

unsigned	mMaxBoxIndex

bool	mIsPeriodicInX

bool	mIsPeriodicInY

bool	mIsPeriodicInZ

bool	mIsPeriodicAcrossProcs

bool	mAreLocalBoxesSet

DistributedVectorFactory *	mpDistributedBoxStackFactory

bool	mCalculateNodeNeighbours

Static Private Attributes
static const double	msFudge = 5e-14

Friends
class	TestDistributedBoxCollection

class	boost::serialization::access

Detailed Description

template<unsigned DIM>
class DistributedBoxCollection< DIM >

A collection of 'boxes' partitioning the domain with information on which nodes are located in which box.

Definition at line 54 of file DistributedBoxCollection.hpp.

Constructor & Destructor Documentation

◆ DistributedBoxCollection()

template<unsigned DIM>

DistributedBoxCollection< DIM >::DistributedBoxCollection	(	double	boxWidth,
		c_vector< double, 2 *DIM >	domainSize,
		bool	isPeriodicInX = `false`,
		bool	isPeriodicInY = `false`,
		bool	isPeriodicInZ = `false`,
		int	localRows = `PETSC_DECIDE`
	)

Parameters

boxWidth	the width of each box (cut-off length in NodeBasedCellPopulation simulations)
domainSize	the size of the domain, in the form (xmin, xmax, ymin, ymax) (etc)
isPeriodicInX	whether the domain is periodic in the x direction (defaults to false)
isPeriodicInY	whether the domain is periodic in the y direction (defaults to true)
isPeriodicInZ	whether the domain is periodic in the z direction (defaults to true)
localRows	the number of local rows in a parallel DistributedBoxCollection.

Note that the domain size may be increased because each process should have at least one slice of boxes in the largest dimension. For example, if the box size is 1 and the domain is [(0,0,0), (3,3,3)] then, if there are more than 3 processes the domain will be swollen to [(0,0,0), (3,3,num_procs)]. The user is warned when this happens.

Definition at line 45 of file DistributedBoxCollection.cpp.

◆ ~DistributedBoxCollection()

template<unsigned DIM>

DistributedBoxCollection< DIM >::~DistributedBoxCollection ( )

Destructor - frees memory allocated to distributed vector.

Definition at line 112 of file DistributedBoxCollection.cpp.

Member Function Documentation

◆ AddPairsFromBox()

template<unsigned DIM>

void DistributedBoxCollection< DIM >::AddPairsFromBox	(	unsigned	boxIndex,
		std::vector< std::pair< Node< DIM > , Node< DIM > > > &	rNodePairs
	)

A method pulled out of CalculateNodePairs methods that adds all pairs of nodes from neighbouring boxes of the box with index boxIndex.

Parameters

boxIndex	the box to add neighbours to.
rNodePairs	the return value, a set of pairs of nodes

Definition at line 1771 of file DistributedBoxCollection.cpp.

References Box< DIM >::rGetNodesContained().

◆ CalculateBoundaryNodePairs()

template<unsigned DIM>

void DistributedBoxCollection< DIM >::CalculateBoundaryNodePairs	(	std::vector< Node< DIM > * > &	rNodes,
		std::vector< std::pair< Node< DIM > , Node< DIM > > > &	rNodePairs
	)

The same as CalculateNodePairs() only we only work on boxes that are ''not'' interior on this process. I.e. some of their local boxes are halo boxes.

Parameters

rNodes	all the nodes to be consider
rNodePairs	the return value, a set of pairs of nodes

Definition at line 1743 of file DistributedBoxCollection.cpp.

◆ CalculateContainingBox() [1/2]

template<unsigned DIM>

unsigned DistributedBoxCollection< DIM >::CalculateContainingBox ( c_vector< double, DIM > & rLocation )

Parameters

rLocation The point

Returns: the global index of the box that contains the rLocation.

Definition at line 315 of file DistributedBoxCollection.cpp.

◆ CalculateContainingBox() [2/2]

template<unsigned DIM>

unsigned DistributedBoxCollection< DIM >::CalculateContainingBox ( Node< DIM > * pNode )

Parameters

pNode address of the node

Returns: the global index of the box that contains pNode.

Definition at line 307 of file DistributedBoxCollection.cpp.

References Node< SPACE_DIM >::rGetLocation().

Referenced by FineCoarseMeshPair< DIM >::SetUpBoxes().

◆ CalculateGlobalIndex()

template<unsigned DIM>

unsigned DistributedBoxCollection< DIM >::CalculateGlobalIndex ( c_vector< unsigned, DIM > gridIndices )

Given the (i,j,k) grid indices of a box in the collection, calculate its global index.

Parameters

gridIndices the (i,j,k) grid indices of the box

Returns: the global index of the box in the collection.

Todo:: #2308 etc. We need to make allowance for periodicity here...

Definition at line 273 of file DistributedBoxCollection.cpp.

◆ CalculateGridIndices()

template<unsigned DIM>

c_vector< unsigned, DIM > DistributedBoxCollection< DIM >::CalculateGridIndices ( unsigned globalIndex )

Calculate x,y,z indices of box given its 'global' index.

Parameters

globalIndex the global index of the box

Returns: the grid indices (boxes across, boxes up, boxes deep) of a box

Definition at line 357 of file DistributedBoxCollection.cpp.

◆ CalculateInteriorNodePairs()

template<unsigned DIM>

void DistributedBoxCollection< DIM >::CalculateInteriorNodePairs	(	std::vector< Node< DIM > * > &	rNodes,
		std::vector< std::pair< Node< DIM > , Node< DIM > > > &	rNodePairs
	)

The same as CalculateNodePairs() only we only work on boxes that are interior on this process. I.e. none of their local boxes are halo boxes.

Parameters

rNodes	all the nodes to be consider
rNodePairs	the return value, a set of pairs of nodes

Definition at line 1699 of file DistributedBoxCollection.cpp.

◆ CalculateNodePairs()

template<unsigned DIM>

void DistributedBoxCollection< DIM >::CalculateNodePairs	(	std::vector< Node< DIM > * > &	rNodes,
		std::vector< std::pair< Node< DIM > , Node< DIM > > > &	rNodePairs
	)

Compute all the pairs of (potentially) connected nodes for cell_based simulations, ie nodes which are in a local box to the box containing the first node. **Note: the user still has to check that the node pairs are less than the cut-off distance apart.** The pairs are checked so that index1 < index2, so each connected pair of nodes is only in the set once.

Parameters

rNodes	all the nodes to be consider
rNodePairs	the return value, a set of pairs of nodes

Definition at line 1660 of file DistributedBoxCollection.cpp.

◆ CalculateNumberOfNodesInEachStrip()

template<unsigned DIM>

std::vector< int > DistributedBoxCollection< DIM >::CalculateNumberOfNodesInEachStrip ( )

Calculate how many cells lie in each strip / face of boxes, used in load balancing

Returns: A vector containing the number of nodes in each of the strips of boxes.

Definition at line 1836 of file DistributedBoxCollection.cpp.

◆ EmptyBoxes()

template<unsigned DIM>

void DistributedBoxCollection< DIM >::EmptyBoxes ( )

Remove the list of nodes stored in each box.

Definition at line 118 of file DistributedBoxCollection.cpp.

◆ GetAreLocalBoxesSet()

template<unsigned DIM>

bool DistributedBoxCollection< DIM >::GetAreLocalBoxesSet ( ) const

Returns: Whether or not the local boxes have been set up.

Definition at line 435 of file DistributedBoxCollection.cpp.

◆ GetBoxWidth()

template<unsigned DIM>

double DistributedBoxCollection< DIM >::GetBoxWidth ( ) const

Returns: mBoxWidth

Definition at line 441 of file DistributedBoxCollection.cpp.

◆ GetIsPeriodicAcrossProcs()

template<unsigned DIM>

bool DistributedBoxCollection< DIM >::GetIsPeriodicAcrossProcs ( ) const

Returns: Whether the domain is periodic across processors

Definition at line 465 of file DistributedBoxCollection.cpp.

◆ GetIsPeriodicAllDims()

template<unsigned DIM>

c_vector< bool, DIM > DistributedBoxCollection< DIM >::GetIsPeriodicAllDims ( ) const

A function to get whether each dimension is periodic

Returns: A vector containing booleans of the periodicity

Definition at line 471 of file DistributedBoxCollection.cpp.

◆ GetIsPeriodicInX()

template<unsigned DIM>

bool DistributedBoxCollection< DIM >::GetIsPeriodicInX ( ) const

Returns: Whether the domain is periodic in x

Definition at line 447 of file DistributedBoxCollection.cpp.

◆ GetIsPeriodicInY()

template<unsigned DIM>

bool DistributedBoxCollection< DIM >::GetIsPeriodicInY ( ) const

Returns: Whether the domain is periodic in y

Definition at line 453 of file DistributedBoxCollection.cpp.

◆ GetIsPeriodicInZ()

template<unsigned DIM>

bool DistributedBoxCollection< DIM >::GetIsPeriodicInZ ( ) const

Returns: Whether the domain is periodic in z

Definition at line 459 of file DistributedBoxCollection.cpp.

◆ GetNumBoxes()

template<unsigned DIM>

unsigned DistributedBoxCollection< DIM >::GetNumBoxes ( )

Returns: the total (global) number of boxes.

Definition at line 417 of file DistributedBoxCollection.cpp.

◆ GetNumLocalBoxes()

template<unsigned DIM>

unsigned DistributedBoxCollection< DIM >::GetNumLocalBoxes ( )

Returns: the number of locally owned boxes. Not including halos.

Definition at line 423 of file DistributedBoxCollection.cpp.

◆ GetNumLocalRows()

template<unsigned DIM>

unsigned DistributedBoxCollection< DIM >::GetNumLocalRows ( ) const

Returns: the number of local rows / faces (2d, 3d) of boxes owned.

Definition at line 231 of file DistributedBoxCollection.cpp.

Referenced by DistributedBoxCollection< DIM >::DistributedBoxCollection().

◆ GetNumRowsOfBoxes()

template<unsigned DIM>

unsigned DistributedBoxCollection< DIM >::GetNumRowsOfBoxes ( ) const

Returns: the number of rows in the DIM-1th direction on this process.

Definition at line 487 of file DistributedBoxCollection.cpp.

◆ GetProcessOwningNode()

template<unsigned DIM>

unsigned DistributedBoxCollection< DIM >::GetProcessOwningNode ( Node< DIM > * pNode )

Get the process that should own this node. Currently only returns +/-1 of this process so assumes nodes don't move too far. //\ todo this should be fixed.

Parameters

pNode the node to be tested

Returns: the ID of the process that should own the node.

Definition at line 1609 of file DistributedBoxCollection.cpp.

References PetscTools::AmMaster(), PetscTools::AmTopMost(), PetscTools::GetMyRank(), and PetscTools::GetNumProcs().

◆ IsBoxOwned()

template<unsigned DIM>

bool DistributedBoxCollection< DIM >::IsBoxOwned ( unsigned globalIndex )

Parameters

globalIndex the global index of the box.

Returns: whether the box with global index globalIndex is owned by this process.

Definition at line 237 of file DistributedBoxCollection.cpp.

Referenced by FineCoarseMeshPair< DIM >::SetUpBoxes().

◆ IsHaloBox()

template<unsigned DIM>

bool DistributedBoxCollection< DIM >::IsHaloBox ( unsigned globalIndex )

Parameters

globalIndex the global index of the box.

Returns: whether the box with global index globalIndex is a halo to this process.

Definition at line 243 of file DistributedBoxCollection.cpp.

◆ IsInteriorBox()

template<unsigned DIM>

bool DistributedBoxCollection< DIM >::IsInteriorBox ( unsigned globalIndex )

Get whether the box with global index globalIndex is interior on this process. A box is interior if it doesn't share any boundary (even of zero length) with a halo box.

Parameters

globalIndex the global index of the box to check.

Returns: whether the box is interior or not.

Definition at line 265 of file DistributedBoxCollection.cpp.

◆ IsOwned() [1/2]

template<unsigned DIM>

bool DistributedBoxCollection< DIM >::IsOwned ( c_vector< double, DIM > & location )

Parameters

location the location to test.

Returns: whether the point at location is owned on this process.

Definition at line 1601 of file DistributedBoxCollection.cpp.

◆ IsOwned() [2/2]

template<unsigned DIM>

bool DistributedBoxCollection< DIM >::IsOwned ( Node< DIM > * pNode )

Parameters

pNode the node to test.

Returns: whether the point at pNode->rGetLocation() is owned on this process.

Definition at line 1593 of file DistributedBoxCollection.cpp.

Referenced by FineCoarseMeshPair< DIM >::SetUpBoxes().

◆ LoadBalance()

template<unsigned DIM>

int DistributedBoxCollection< DIM >::LoadBalance ( std::vector< int > localDistribution )

A helper function to work out the optimal number of rows to be owned by this process, to balance the number of nodes.

Parameters

localDistribution a vector containing the number of nodes in each row/face of boxes in 2d/3d

Returns: the updated number of rows, which will differ from current number by at most 2.

Shift information on distribution of nodes to the right, so processes can manage their left/bottom/back boundary (1d/2d/3d)

Calculate change in balance of loads by shifting the left/bottom boundary in either direction

Definition at line 493 of file DistributedBoxCollection.cpp.

References PetscTools::AmMaster(), PetscTools::AmTopMost(), and PetscTools::GetMyRank().

◆ rGetBox()

template<unsigned DIM>

Box< DIM > & DistributedBoxCollection< DIM >::rGetBox ( unsigned boxIndex )

If this box is out-of-bounds to the local process then it will attempt to return a halo box (and trip an assertion is the box is completely out of scope.

Parameters

boxIndex the index of the box to return

Returns: a reference to the box with global index boxIndex.

Definition at line 394 of file DistributedBoxCollection.cpp.

Referenced by FineCoarseMeshPair< DIM >::CollectElementsInContainingBox(), FineCoarseMeshPair< DIM >::CollectElementsInLocalBoxes(), and FineCoarseMeshPair< DIM >::SetUpBoxes().

◆ rGetDomainSize()

template<unsigned DIM>

c_vector< double, 2 *DIM > DistributedBoxCollection< DIM >::rGetDomainSize ( ) const

Returns: mDomainSize

Definition at line 429 of file DistributedBoxCollection.cpp.

◆ rGetHaloBox()

template<unsigned DIM>

Box< DIM > & DistributedBoxCollection< DIM >::rGetHaloBox ( unsigned boxIndex )

Get a halo box.

Parameters

boxIndex the index of the box to return

Returns: a reference to the halo box with global index boxIndex.

Definition at line 407 of file DistributedBoxCollection.cpp.

◆ rGetHaloNodesLeft()

template<unsigned DIM>

std::vector< unsigned > & DistributedBoxCollection< DIM >::rGetHaloNodesLeft ( )

Returns: mHaloNodesRight the list of nodes that are close to the left boundary

Definition at line 1648 of file DistributedBoxCollection.cpp.

◆ rGetHaloNodesRight()

template<unsigned DIM>

std::vector< unsigned > & DistributedBoxCollection< DIM >::rGetHaloNodesRight ( )

Returns: mHaloNodesRight the list of nodes that are close to the right boundary

Definition at line 1642 of file DistributedBoxCollection.cpp.

◆ rGetLocalBoxes()

template<unsigned DIM>

std::set< unsigned > & DistributedBoxCollection< DIM >::rGetLocalBoxes ( unsigned boxIndex )

Get the set of all the local boxes, i.e. itself and its nearest-neighbours.

Parameters

boxIndex the index of the box

Returns: the set containing the indices of boxes local to box boxIndex. i.e. the box boxIndex itself and its nearest-neighbours.

Definition at line 1585 of file DistributedBoxCollection.cpp.

Referenced by FineCoarseMeshPair< DIM >::CollectElementsInLocalBoxes().

◆ serialize()

template<unsigned DIM>

template<class Archive >

void DistributedBoxCollection< DIM >::serialize	(	Archive &	archive,
		const unsigned int	version
	)

inlineprivate

Serialize the box collection. It is possible to save and load on a different # of processes.

Parameters

archive	the archive.
version	the version number.

Definition at line 146 of file DistributedBoxCollection.hpp.

◆ SetCalculateNodeNeighbours()

template<unsigned DIM>

void DistributedBoxCollection< DIM >::SetCalculateNodeNeighbours ( bool calculateNodeNeighbours )

Set whether to record node neighbour in the map rNodeNeighbours during CalculateNodePairs. Set to false for efficiency if not needed.

Parameters

calculateNodeNeighbours whether to store the neighbours.

Definition at line 1654 of file DistributedBoxCollection.cpp.

◆ SetupAllLocalBoxes()

template<unsigned DIM>

void DistributedBoxCollection< DIM >::SetupAllLocalBoxes ( )

Set up the local boxes (ie itself and its nearest-neighbours) for each of the boxes.

Definition at line 834 of file DistributedBoxCollection.cpp.

References NEVER_REACHED.

Referenced by FineCoarseMeshPair< DIM >::SetUpBoxes().

◆ SetupHaloBoxes()

template<unsigned DIM>

void DistributedBoxCollection< DIM >::SetupHaloBoxes ( )

private

Setup the halo box structure on this process. (Private method since this is called as a helper method by the constructor.)

Sets up the containers mHaloBoxes, mHalosRight, mHalosLeft

Definition at line 131 of file DistributedBoxCollection.cpp.

Referenced by DistributedBoxCollection< DIM >::DistributedBoxCollection().

◆ SetupLocalBoxesHalfOnly()

template<unsigned DIM>

void DistributedBoxCollection< DIM >::SetupLocalBoxesHalfOnly ( )

Set up the local boxes (ie itself and its nearest-neighbours) for each of the boxes. This method just sets up half of the local boxes (for example, in 1D, local boxes for box0 = {1} local boxes for box1 = {2} not {0,2}, and so on. Similar to 2d, 3d.

Definition at line 581 of file DistributedBoxCollection.cpp.

References EXCEPTION, and NEVER_REACHED.