SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM > Class Template Reference

Node in the asynchronous Berger-Rigoutsos (BR) dendogram. More...

#include <source/mesh/clustering/AsyncBergerRigoutsosNode.h>

Inheritance diagram for SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >:

[legend]List of all members.

Public Types
enum	OwnerMode { SINGLE_OWNER = 0, MOST_OVERLAP = 1, FEWEST_OWNED = 2, LEAST_ACTIVE = 3 }
typedef hier::LayerNodeSet< DIM >::Node	GraphNode
	Shorthand for the box-graph node corresponding to boxes.
typedef hier::LayerNodeSet< DIM >::NodeContainer	GraphNodeContainer
	Shorthand for a container of graph-nodes.
typedef hier::LayerEdgeSet< DIM >::NabrContainer	GraphNabrContainer
	Shorthand for a container of neighbor graph-nodes.
typedef hier::LayerEdgeSet< DIM >::Connectivity	Connectivity
	Shortthand for the connectivity between two sets of graph nodes.
typedef std::set< int >	IntSet
	Shorthand for a sorted, possibly incontiguous, set of integers.
Public Member Functions
	AsyncBergerRigoutsosNode (CommonParams *common_params, const hier::Box< DIM > *bound_box=NULL, mesh::AsyncBergerRigoutsosNode< DIM > *parent=NULL, const int child_number=1)
	Construct a node of a BR dendogram.
	~AsyncBergerRigoutsosNode (void)
	Destructor.
void	runAlgorithm ()
	Run the BR algorithm to find boxes.
Algorithm mode settings
void	setMaxGhostCellWidth (const hier::IntVector< DIM > &max_gcw)
	Set the maximum ghost cell width used for checking overlaps.
void	setAlgorithmAdvanceMode (const std::string &algo_advance_mode)
	Set the mode for advancing the asynchronous implementation.
void	setOwnerMode (const std::string &mode)
	Set the method for choosing the owner. Choices: "MOST_OVERLAP" Ownership is given to the processor with the most overlap on the candidate box. Default. "SINGLE_OWNER" In single-owner mode, the initial owner (process 0) always participates and owns all dendogram nodes. "FEWEST_OWNED" Choose the processor that owns the fewest dendogram nodes when the choice is made. This is meant to relieve bottle-necks caused by excessive ownership. "LEAST_ACTIVE" Choose the processor that participates in the fewest number of dendogram nodes when the choice is made. This is meant to relieve bottle-necks caused by excessive participation.
void	setUseLevelBoxes (bool flag)
	Switch on or off the use of global level boxes.
void	setComputeEdges (int compute_edges)
	Edge computation flag.
Access to outputs
const hier::LayerNodeSet< DIM > &	getNewNodes () const
	Get the output boxes in a hier::LayerNodeSet<DIM> form.
const Connectivity &	getNewCnect () const
	Get the connectivity between input and output graph nodes (between the tagged and new graph nodes).
Developer's methods for analysis and debugging this class.
virtual void	printClassData (std::ostream &os, int detail_level=0) const
int	getMaxNodes () const
	Max number of local nodes for dendogram.
int	getMaxGeneration () const
	max generation count for the local nodes in the dendogram.
int	getMaxOwnership () const
	Max number of locally owned nodes in the dendogram.
double	getAvgNumberOfCont () const
	Average number of continuations for local nodes in dendogram.
int	getMaxNumberOfCont () const
	Max number of continuations for local nodes in dendogram.
int	getNumBoxesGenerated () const
	Number of boxes generated (but not necessarily owned) on the local process.
void	setLogNodeHistory (bool flag)
	Set whether to log dendogram node action history (useful for debugging).
Classes
struct	CommonParams
	Parameters shared among all dendogram nodes in an dendogram and collectively managed by those nodes. More...

---

Detailed Description

template<int DIM>
class SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >

Node in the asynchronous Berger-Rigoutsos (BR) dendogram.

In mesh generation, the BR algorithm can be used to cluster tagged cells into boxes. This algorithm is described in Berger and Rigoutsos, IEEE Trans. on Sys, Man, and Cyber (21)5:1278-1286.

This class implements the BR algorithm to execute in a non-recursive way, in order to improve parallel efficiency over recursive implementations. To facilitate a non-recursive implementation, data in the recursive tree is maintained in a "BR dendogram", nodes of which are instances of this class.

Clarification on the uses of the word "node":

• Dendogram node: Node in the BR dendogram (this class).
• Graph node: Node in a box graph. The box graph is the form of the outputs of this class. Each output graph node corresponds to a box generated by the BR algorithm.
• Processor: MPI process id. This is called a node in some context. For clarity, we avoid this use of "node".

Each dendogram node is associated with a candidate box, an owner process coordinating distributed computations on the box and a group of processors participating in those computations. Should the candidate box be one of the final output boxes, the owner also owns the graph node associated with the box.

To use this class:

1. Construct an object of type CommonParams.
2. Construct the root node of the dendogram using the CommonParams object.
3. Finetune the algorithm settings using the methods under "Algorithm settings".
4. If needed, various non-algorithmic flags using set...() methods under "Methods for analysis and debugging".
5. Initiate the algorithm using runAlgorithm() in the job_relauncher parameter in the CommonParams object.
6. Get the output graph nodes and edges using methods under "Access to outputs".

This class creates its output in a distributed nested-level box-graph (DNBG) format. The output is distributed over all processes running the algorithm, with each process owning a subset of the DNBG. The 2 primary outputs of this implementation are:

1. Set of graph nodes containing input tags. Each node corresponds to an output box. See getNewNodes() and hier::LayerNodeSet<DIM>.
2. Connectivity between graph nodes on the tagged level and the new graph nodes. See getNewCnect() and hier::LayerEdgeSet<DIM>.

---

Member Typedef Documentation

template<int DIM>

typedef hier::LayerNodeSet<DIM>::Node SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::GraphNode

Shorthand for the box-graph node corresponding to boxes.

template<int DIM>

typedef hier::LayerNodeSet<DIM>::NodeContainer SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::GraphNodeContainer

Shorthand for a container of graph-nodes.

template<int DIM>

typedef hier::LayerEdgeSet<DIM>::NabrContainer SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::GraphNabrContainer

Shorthand for a container of neighbor graph-nodes.

template<int DIM>

typedef hier::LayerEdgeSet<DIM>::Connectivity SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::Connectivity

Shortthand for the connectivity between two sets of graph nodes.

template<int DIM>

typedef std::set<int> SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::IntSet

Shorthand for a sorted, possibly incontiguous, set of integers.

---

Member Enumeration Documentation

template<int DIM>

enum SAMRAI::mesh::AsyncBergerRigoutsosNode::OwnerMode

Enumerator:

SINGLE_OWNER
MOST_OVERLAP
FEWEST_OWNED
LEAST_ACTIVE

---

Constructor & Destructor Documentation

template<int DIM>

SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::AsyncBergerRigoutsosNode	(	CommonParams *	common_params,
		const hier::Box< DIM > *	bound_box = NULL,
		mesh::AsyncBergerRigoutsosNode< DIM > *	parent = NULL,
		const int	child_number = 1
	)

Construct a node of a BR dendogram.

Construct a node node of a BR dendogram, which you can use to run the BR algorithm.

Parameters:

	common_params	The common parameter object you plan to use to run the ABR algorithm.
	bound_box	Bounding box for tagged cells.
	parent	Parent node of the node being constructed. Set to NULL if you are constructing the root node of the BR dendogram.
	child_number	0 if constructing left child and 1 if constructing right child. Set to 1 if you are constructing the root node of the BR dendogram.

template<int DIM>

SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::~AsyncBergerRigoutsosNode

(

void

)

Destructor.

Deallocate internal data.

---

Member Function Documentation

template<int DIM>

void SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::setMaxGhostCellWidth

(

const hier::IntVector< DIM > &

max_gcw

)

Set the maximum ghost cell width used for checking overlaps.

Overlap checking is done to determine nearest-neighbor relationships when generating connectivity to new graph nodes. If a box grown by this ammount intersects another box, the two boxes are considered neighbors.

By default the max ghost cell width is one in each direction.

template<int DIM>

void SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::setAlgorithmAdvanceMode

(

const std::string &

algo_advance_mode

)

Set the mode for advancing the asynchronous implementation.

Choices are:

• "SYNCHRONOUS" --> wait for each communication stage to complete before moving on, thus resulting in synchronous execution.
• "ROUND_ROBIN" --> check for completed communication stages in round-robin fashion instead of waiting for a specific one.
• "ADVANCE_ANY" --> advance an dendogram node through its communication stage by using tbox::AsyncCommStage::advanceAny().
• "ADVANCE_SOME" --> advance an dendogram node through its communication stage by using tbox::AsyncCommStage::advanceSome().

The default is "ADVANCE_SOME".

Asynchronous modes are NOT guaranteed to compute the output graph nodes in any particular order. The order depends on the ordering of message completion, which is not deterministic. If you require consistent outputs, we suggest you have a scheme for reordering the output boxes.

template<int DIM>

void SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::setOwnerMode

(

const std::string &

mode

)

Set the method for choosing the owner. Choices:

• "MOST_OVERLAP" Ownership is given to the processor with the most overlap on the candidate box. Default.
• "SINGLE_OWNER" In single-owner mode, the initial owner (process 0) always participates and owns all dendogram nodes.
• "FEWEST_OWNED" Choose the processor that owns the fewest dendogram nodes when the choice is made. This is meant to relieve bottle-necks caused by excessive ownership.
• "LEAST_ACTIVE" Choose the processor that participates in the fewest number of dendogram nodes when the choice is made. This is meant to relieve bottle-necks caused by excessive participation.

Experiments show that "MOST_OVERLAP" gives the best clustering speed, while "SINGLE_OWNER" may give a faster output globalization (since you don't need an all-gather).

template<int DIM>

void SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::setUseLevelBoxes

(

bool

flag

)

Switch on or off the use of global level boxes.

If off, the global level boxes will neither be used nor be generated. This feature is in anticipation of future support for the distributed nested-level box graph in SAMRAI.

template<int DIM>

void SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::setComputeEdges

(

int

compute_edges

)

Edge computation flag.

Valid values to set are:

• 0 = No edge computation.
• 1 = Compute directed edges from input to output graph nodes. With this option, it is possible to determine output nodes neighboring any input nodes, but not possible to determine input nodes neighboring a specific output node.
• 2 = Compute directed edges from input to output graph nodes as well as the reverse. With this option, it is possible to determine output nodes neighboring any input nodes, as well as input nodes neighboring any output node. This is accomplished using an additional edge-sharing communication after all graph nodes have been created.

By default, the value is 2.

template<int DIM>

void SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::runAlgorithm

(

)

Run the BR algorithm to find boxes.

template<int DIM>

const hier::LayerNodeSet< DIM > & SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::getNewNodes

(

)

const

Get the output boxes in a hier::LayerNodeSet<DIM> form.

template<int DIM>

const hier::LayerEdgeSet< DIM >::Connectivity & SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::getNewCnect

(

)

const

Get the connectivity between input and output graph nodes (between the tagged and new graph nodes).

The connectivity data generated depend on the flag set using setComputeEdges().

template<int DIM>

void SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::printClassData	(	std::ostream &	os,
		int	detail_level = 0
	)			const [virtual]

template<int DIM>

int SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::getMaxNodes

(

)

const

Max number of local nodes for dendogram.

template<int DIM>

int SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::getMaxGeneration

(

)

const

max generation count for the local nodes in the dendogram.

template<int DIM>

int SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::getMaxOwnership

(

)

const

Max number of locally owned nodes in the dendogram.

template<int DIM>

double SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::getAvgNumberOfCont

(

)

const

Average number of continuations for local nodes in dendogram.

template<int DIM>

int SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::getMaxNumberOfCont

(

)

const

Max number of continuations for local nodes in dendogram.

template<int DIM>

int SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::getNumBoxesGenerated

(

)

const

Number of boxes generated (but not necessarily owned) on the local process.

template<int DIM>

void SAMRAI::mesh::AsyncBergerRigoutsosNode< DIM >::setLogNodeHistory

(

bool

flag

)

Set whether to log dendogram node action history (useful for debugging).

---

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

• source/mesh/clustering/AsyncBergerRigoutsosNode.h
• source/mesh/clustering/AsyncBergerRigoutsosNode.C

---