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. This class is derived from the abstract base class LoadBalanceStrategy<DIM>; thus, it is a concrete implementation of the load balance Strategy pattern interface.
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 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 | setWorkloadPatchDataIndex (int data_id, int level_number=-1) |
void | setUniformWorkload (int level_number=-1) |
void | setBinPackMethod (const 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 (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 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. The default or input value will remain in use for all levels until reset by the member function.
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.
- 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
|
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. |
|
|
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. |
|
|
The virtual destructor releases all internal storage. |
Member Function Documentation
|
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. |
|
|
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. An invalid value (i.e., < 0) indicates that a spatially-uniform work estimate will be used. The default value is -1 (undefined) implying the uniform work estimate. |
| 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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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 >. |
|
Print out all members of the class instance to given output stream. |
The documentation for this class was generated from the following files:
Generated on Fri Dec 2 11:29:26 2005 for SAMRAI by
1.4.2