Class LoadBalancer<DIM> provides load balancing routines for AMR hierarchy levels based on either uniform or non-uniform workload estimates.
More...
#include <ibamr/IBStrategySet.h>
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 |
Private Member Functions | |
| LoadBalancer (const LoadBalancer< DIM > &) | |
| void | operator= (const LoadBalancer< DIM > &) |
| void | getFromInput (tbox::Pointer< tbox::Database > db) |
| void | chopUniformSingleBox (hier::BoxArray< DIM > &out_boxes, tbox::Array< double > &out_workloads, const hier::Box< DIM > &in_box, 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 hier::BoxArray< DIM > &physical_domain) const |
| void | chopBoxesWithUniformWorkload (hier::BoxArray< DIM > &out_boxes, tbox::Array< double > &out_workloads, const hier::BoxList< DIM > &in_boxes, const tbox::Pointer< hier::PatchHierarchy< DIM > > hierarchy, int level_number, 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 hier::BoxArray< DIM > &physical_domain) const |
| void | chopBoxesWithNonuniformWorkload (hier::BoxArray< DIM > &out_boxes, tbox::Array< double > &out_workloads, const hier::BoxList< DIM > &in_boxes, const tbox::Pointer< hier::PatchHierarchy< DIM > > hierarchy, int level_number, const hier::IntVector< DIM > &ratio_to_coarsest_hierarchy_level, int wrk_indx, 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 hier::BoxArray< DIM > &physical_domain) const |
| void | binPackBoxes (hier::BoxArray< DIM > &boxes, hier::ProcessorMapping &mapping, tbox::Array< double > &workloads, const std::string &bin_pack_method) const |
| int | getWorkloadDataId (int level_number) const |
| double | getMaxWorkloadFactor (int level_number) const |
| double | getWorkloadTolerance (int level_number) const |
| std::string | getBinPackMethod (int level_number) const |
Detailed Description
template<int DIM>
class SAMRAI::mesh::LoadBalancer< DIM >
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
◆ LoadBalancer() [1/3]
| 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.
◆ LoadBalancer() [2/3]
| 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.
◆ ~LoadBalancer()
|
virtual |
The virtual destructor releases all internal storage.
◆ LoadBalancer() [3/3]
|
private |
Member Function Documentation
◆ setMaxWorkloadFactor()
| 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.
◆ setWorkloadTolerance()
| 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.
◆ setWorkloadPatchDataIndex()
| 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.
◆ setUniformWorkload()
| 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.
◆ setBinPackMethod()
| 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.
◆ setIgnoreLevelDomainIsSingleBox()
| 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.
◆ getLoadBalanceDependsOnPatchData()
|
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 >.
◆ loadBalanceBoxes()
|
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 >.
◆ printClassData()
|
virtual |
Print out all members of the class instance to given output stream.
◆ operator=()
|
private |
◆ getFromInput()
|
private |
◆ chopUniformSingleBox()
|
private |
◆ chopBoxesWithUniformWorkload()
|
private |
◆ chopBoxesWithNonuniformWorkload()
|
private |
◆ binPackBoxes()
|
private |
◆ getWorkloadDataId()
|
private |
◆ getMaxWorkloadFactor()
|
private |
◆ getWorkloadTolerance()
|
private |
◆ getBinPackMethod()
|
private |
Member Data Documentation
◆ d_object_name
|
private |
◆ d_processor_layout_specified
|
private |
◆ d_processor_layout
|
private |
◆ d_ignore_level_box_union_is_single_box
|
private |
◆ d_master_workload_data_id
|
private |
◆ d_master_max_workload_factor
|
private |
◆ d_master_workload_tolerance
|
private |
◆ d_master_bin_pack_method
|
private |
◆ d_workload_data_id
|
private |
◆ d_max_workload_factor
|
private |
◆ d_workload_tolerance
|
private |
◆ d_bin_pack_method
|
private |
◆ d_opt_for_single_box
|
private |
◆ t_load_balance_boxes
|
private |
◆ t_load_balance_boxes_remove_intersection
|
private |
◆ t_bin_pack_boxes
|
private |
◆ t_bin_pack_boxes_sort
|
private |
◆ t_bin_pack_boxes_pack
|
private |
◆ t_chop_boxes
|
private |
The documentation for this class was generated from the following file:
- /samrai/include/LoadBalancer.h
