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

Class LoadBalancer<DIM> provides load balancing routines for AMR hierarchy levels based on either uniform or non-uniform workload estimates. More...

#include <source/mesh/load_balance/LoadBalancer.h>

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

[legend]List of all members.

Public Member Functions
	LoadBalancer (const std::string &name, tbox::Pointer< tbox::Database > input_db=(tbox::Database *) NULL)
	LoadBalancer (tbox::Pointer< tbox::Database > input_db=(tbox::Database *) NULL)
virtual	~LoadBalancer ()
void	setMaxWorkloadFactor (double factor, int level_number=-1)
void	setWorkloadTolerance (double tolerance, int level_number=-1)
void	setWorkloadPatchDataIndex (int data_id, int level_number=-1)
void	setUniformWorkload (int level_number=-1)
void	setBinPackMethod (const std::string &method, int level_number=-1)
void	setIgnoreLevelDomainIsSingleBox (bool flag)
bool	getLoadBalanceDependsOnPatchData (int level_number) const
void	loadBalanceBoxes (hier::BoxArray< DIM > &out_boxes, hier::ProcessorMapping &mapping, const hier::BoxList< DIM > &in_boxes, const tbox::Pointer< hier::PatchHierarchy< DIM > > hierarchy, int level_number, const hier::BoxArray< DIM > &physical_domain, const hier::IntVector< DIM > &ratio_to_hierarchy_level_zero, const hier::IntVector< DIM > &min_size, const hier::IntVector< DIM > &max_size, const hier::IntVector< DIM > &cut_factor, const hier::IntVector< DIM > &bad_interval) const
virtual void	printClassData (std::ostream &os) const

---

Detailed Description

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

Class LoadBalancer<DIM> provides load balancing routines for AMR hierarchy levels based on either uniform or non-uniform workload estimates.

This class is derived from the abstract base class LoadBalanceStrategy<DIM>; thus, it is a concrete implementation of the load balance Strategy pattern interface.

Load balancing operations, whether based on uniform or non-uniform workloads, can be specified for each level in the hierarchy individually or for the entire hierarchy. Basic load balance parameters can be set from an input file, while more complex behavior can be set at run-time via member functions, including dynamic reconfiguration of balance operations.

Required input keys: NONE

Optional input keys, data types, and defaults:

• processor_layout Integer array (length = DIM) indicating the way in which the domain should be chopped when a level can be described as a single parallelepiped region (i.e., a box). If no input value is provided, or if the product of these entries does not equal the number of processors, then the processor layout computed will be computed from the dimensions of the domain box and the number of processors in use if necessary.

NOTE: The largest patch size constraint specified in the input for the GriddingAlgorithm<DIM> object takes precedence over the processor layout specification. That is, if the processor layout indicates that the resulting level patches would be larger than the largest patch size, the layout will be ignored and boxes obeying the patch size constrint will result.

• bin_pack_method String value indicating the type of bin packing to use to map patches to processors. Currently, two options are supported: "GREEDY", "SPATIAL". The "GREEDY" process simply maps each patch (box) to the first processor (bin), in ascending tbox::MPI process number, whose difference between the average workload and its current workload is less than the workload of the patch in question. The "SPATIAL" process first constructs an ordering of the patches (boxes) by passing a Morton-type curve through the center of each box. Then, it attempts to map the patches to processors by assigning patches that are near each other on the curve to the same processor. If no input value is specified, a default value of "SPATIAL" is used. The input value will be used for all levels and will remain so until reset via the setBinPackMethod() member function below.

• max_workload_factor Double array (length = number of levels) used during the box-splitting phase to determine which boxes to split. Specifically, boxes will be chopped if their estimated workload is greater than max_workload_factor * A, where A is the average workload (i.e., A = (total work)/(nume processors)). The default value for this parameter is 1.0. It can be set to any value greater than zero, either in the input file or via the setMaxWorkloadFactor() member function below.

Example input:

max_workload_factor = 0.8

Sets the workload factor to 0.8 for all levels.

max_worklaod_factor = 0.8 , 0.9

Sets the workload factor to 0.8 for level 0 and 0.9 for all other levels.

NOTE: If a length is less than max levels then finest value specified is use for finer levels. If length is greater than max levels, the values are ignored.

NOTE: Setting this value > 1.0 increases the splitting threshold which effectively reduces the total number of boxes generated. Setting it less than 1.0 decreases the splitting threshold and will generally increase the total number of boxes.

• workload_tolerance Double array (length = number of levels) used during the box-splitting phase to determine which boxes to split. The tolerance value can be use to prevent splitting of boxes when the computed box workload is close to the computed ideal workload. A box is split if:

( box_workload <= ( (1. + workload_tolerance) * ideal_workload ) )

Tolerance values should be greater than or equal to 0.0 and less then 1.0. Large values will probably have undesirable results. The default value for this parameter is 0.0. It can be set to either in the input file or via the setWorkloadTolerance() member function below.

NOTE: If a length is less than max levels then finest value specified is use for finer levels. If length is greater than max levels, the values are ignored.

• ignore_level_box_union_is_single_box Boolean flag to control chopping of level boxes when the union of the input boxes passed to the loadBalanceBoxes() routine is a single box. The default value is false, which means that the domain will be chopped to make patch boxes based on the (single box) union of the boxes describing the level regardless of the input boxes. When the value is set to true, either via the setIgnoreLevelDomainIsSingleBox() function or an input file, the domain will be chopped by chopping each of the input boxes.

A sample input file entry might look like:

 *
 *    processor_layout = 4 , 4 , 4    // number of processors is 64
 *    bin_pack = "GREEDY"
 *    max_workload_factor = 0.9
 *    ignore_level_box_union_is_single_box = TRUE
 *
 * 

See also:

mesh::LoadBalanceStrategy

---

Constructor & Destructor Documentation

template<int DIM>

SAMRAI::mesh::LoadBalancer< DIM >::LoadBalancer	(	const std::string &	name,
		tbox::Pointer< tbox::Database >	input_db = (tbox::Database *) NULL
	)

Construct load balancer object, including setting default object state and reading input data from the input data base, if required.

Parameters:

	name	User-defined string identifier used for error reporting. This string must be non-empty.
	input_db	(optional) database pointer providing parameters from input file. This pointer may be null indicating no input will be read.

template<int DIM>

SAMRAI::mesh::LoadBalancer< DIM >::LoadBalancer

(

tbox::Pointer< tbox::Database >

input_db = (tbox::Database *) NULL

)

Construct load balancer object, including setting default object state and reading input data from the input data base, if required. The only difference between this constructor and the previous one is the string identifier input. If this constructor is used, the default object name "LoadBalancer" applies.

Parameters:

input_db

(optional) database pointer providing parameters from input file. This pointer may be null indicating no input will be read.

template<int DIM>

SAMRAI::mesh::LoadBalancer< DIM >::~LoadBalancer

(

)

[virtual]

The virtual destructor releases all internal storage.

---

Member Function Documentation

template<int DIM>

void SAMRAI::mesh::LoadBalancer< DIM >::setMaxWorkloadFactor	(	double	factor,
		int	level_number = -1
	)

Set the max workload factor for either the specified level or all hierarchy levels. See discussion about inputs above for information on how this value is used during load balancing operations.

Parameters:

	factor	Double value of multiplier for average workload used in box chopping. The default value is 1.0.
	level_number	Optional integer number for level to which factor is applied. If no value is given, the factor will be used for all levels.

template<int DIM>

void SAMRAI::mesh::LoadBalancer< DIM >::setWorkloadTolerance	(	double	tolerance,
		int	level_number = -1
	)

Set the workload tolerance for either the specified level or all hierarchy levels. See discussion about inputs above for information on how this value is used during load balancing operations.

Parameters:

	factor	Double value of tolerance. The default value is 0.0;
	level_number	Optional integer number for level to which factor is applied. If no value is given, the value will be used for all levels.

template<int DIM>

void SAMRAI::mesh::LoadBalancer< DIM >::setWorkloadPatchDataIndex	(	int	data_id,
		int	level_number = -1
	)

Configure the load balancer to use the data stored in the hierarchy at the specified descriptor index for estimating the workload on each cell.

Parameters:

	data_id	Integer value of patch data identifier for workload estimate on each cell.
	level_number	Optional integer number for level on which data id is used. If no value is given, the data will be used for all levels.

template<int DIM>

void SAMRAI::mesh::LoadBalancer< DIM >::setUniformWorkload

(

int

level_number = -1

)

Configure the load balancer to load balance boxes by assuming all cells on the specified level or all hierarchy levels are weighted equally.

Parameters:

level_number

Optional integer number for level on which uniform workload estimate will be used. If the level number is not specified, a uniform workload estimate will be used on all levels.

template<int DIM>

void SAMRAI::mesh::LoadBalancer< DIM >::setBinPackMethod	(	const std::string &	method,
		int	level_number = -1
	)

Configure the load balancer to use the bin-packing procedure for mapping patches to processors indicated by the string.

Parameters:

	method	String value indicating bin-packing method to use. See input file description above for valid options. The default value is "GREEDY".
	level_number	Optional integer number for level on which bin-packing method will be used. If no value is given, the prescribed methods will be used on all levels.

template<int DIM>

void SAMRAI::mesh::LoadBalancer< DIM >::setIgnoreLevelDomainIsSingleBox

(

bool

flag

)

Set the boolean flag to control chopping of level boxes when the union of the input boxes passed to the loadBalanceBoxes() routine is a single box. The default value is false, which means that the domain will be chopped to make patch boxes based on the (single box) union of the boxes describing the level regardless of the input boxes. When the value is set to true, the domain will be chopped by chopping each of the input boxes.

Parameters:

flag

Boolean value indicating whether to ignore the set of input boxes to the loadBalanceBoxes() routine when the union of those boxes is a single box.

template<int DIM>

bool SAMRAI::mesh::LoadBalancer< DIM >::getLoadBalanceDependsOnPatchData

(

int

level_number

)

const [virtual]

Return true if load balancing procedure for given level depends on patch data on mesh; otherwise return false. This can be used to determine whether a level needs to be rebalanced although its box configuration is unchanged. This function is pure virtual in the LoadBalanceStrategy<DIM> base class.

Returns:

Boolean value indicating whether load balance depends on patch data.

Parameters:

level_number

Integer patch level number.

Implements SAMRAI::mesh::LoadBalanceStrategy< DIM >.

template<int DIM>

void SAMRAI::mesh::LoadBalancer< DIM >::loadBalanceBoxes	(	hier::BoxArray< DIM > &	out_boxes,
		hier::ProcessorMapping &	mapping,
		const hier::BoxList< DIM > &	in_boxes,
		const tbox::Pointer< hier::PatchHierarchy< DIM > >	hierarchy,
		int	level_number,
		const hier::BoxArray< DIM > &	physical_domain,
		const hier::IntVector< DIM > &	ratio_to_hierarchy_level_zero,
		const hier::IntVector< DIM > &	min_size,
		const hier::IntVector< DIM > &	max_size,
		const hier::IntVector< DIM > &	cut_factor,
		const hier::IntVector< DIM > &	bad_interval
	)			const [virtual]

Given a list of boxes, representing the domain of a level in the AMR hierarchy, generate an array of boxes and an associated processor mapping from which the patches for the level will be generated and assigned. The resulting boxes and processor mapping will be determined based on parameters set via input or member functions above. This function is pure virtual in the LoadBalanceStrategy<DIM> base class.

Parameters:

	out_boxes	Output box array for generating patches on level.
	mapping	Output processor mapping for patches on level.
	in_boxes	Input box list representing union of patches on level.
	hierarchy	Input patch hierarchy in which level will reside.
	level_number	Input integer number of level in patch hierarchy. This value must be >= 0.
	physical_domain	Array of boxes describing the physical extent of the problem domain in the index space associated with the level. This box array cannot be empty.
	ratio_to_hierarchy_level_zero	Input integer vector indicating ratio between index space of level to load balance and hierarchy level 0 (i.e., coarsest hierarchy level).
	min_size	Input integer vector of minimum dimensions for output boxes. All entries must be > 0.
	max_size	Input integer vector of maximum dimensions for output boxes. All entries must be >= min_size.
	cut_factor	Input integer vector used to create boxes with correct dimensions. The length of each box dimension will be an integer multiple of the corresponding cut factor vector entry. All vector entries must be > 0. See hier::BoxUtilities documentation for more details.
	bad_interval	Input integer vector used to create boxes near physical domain boundary with sufficient number of cells. No box face will be closer to the boundary than the corresponding interval of cells to the boundary (the corresponding value is given by the normal direction of the box face) unless the face coincides with the boundary itself. The point of this argument is to have no patch live within a certain ghost cell width of the boundary if its boundary does not coincide with that boundary . That is, all ghost cells along a face will be either in the domain interior or outside the domain. All entries must be >= 0. See hier::BoxUtilities documentation for more details.

Implements SAMRAI::mesh::LoadBalanceStrategy< DIM >.

template<int DIM>

void SAMRAI::mesh::LoadBalancer< DIM >::printClassData

(

std::ostream &

os

)

const [virtual]

Print out all members of the class instance to given output stream.

---

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

• source/mesh/load_balance/LoadBalancer.h
• source/mesh/load_balance/LoadBalancer.C

---