Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

LoadBalance.H

Go to the documentation of this file.
00001 /* _______              __
00002   / ___/ /  ___  __ _  / /  ___
00003  / /__/ _ \/ _ \/  ' \/ _ \/ _ \
00004  \___/_//_/\___/_/_/_/_.__/\___/ 
00005 */
00006 //
00007 // This software is copyright (C) by the Lawrence Berkeley
00008 // National Laboratory.  Permission is granted to reproduce
00009 // this software for non-commercial purposes provided that
00010 // this notice is left intact.
00011 // 
00012 // It is acknowledged that the U.S. Government has rights to
00013 // this software under Contract DE-AC03-765F00098 between
00014 // the U.S.  Department of Energy and the University of
00015 // California.
00016 //
00017 // This software is provided as a professional and academic
00018 // contribution for joint exchange. Thus it is experimental,
00019 // is provided ``as is'', with no warranties of any kind
00020 // whatsoever, no support, no promise of updates, or printed
00021 // documentation. By using this software, you acknowledge
00022 // that the Lawrence Berkeley National Laboratory and
00023 // Regents of the University of California shall have no
00024 // liability with respect to the infringement of other
00025 // copyrights by any part of this software.
00026 //
00027 
00028 // Purpose:
00029 //  LoadBalance() is a global function to compute an assignment
00030 //  of boxes to processors for an AMR mesh hierarchy.  The assignment
00031 //  is made so as to balance the computation and communication
00032 //  workload on each processor (i.e. make it as even as possible).
00033 //
00034 //  ********************************************************
00035 //  CAVEAT: this version ignores the communication workload.
00036 //          It balances ONLY the compute workload.
00037 //  ********************************************************
00038 //
00039 // Usage:
00040 //  The meshes in the AMR hierarchy are represented using
00041 //   a Vector of Vectors of Boxes.
00042 //
00043 //  The computational workload is a real number for each box in the
00044 //   hierarchy, also represented as a Vector of Vectors.
00045 //
00046 //  The communication workload is a real number for each connection
00047 //   between pairs of boxes, which specifies the cost of communication
00048 //   between the two boxes if they are on different processors.  No
00049 //   allowance is made for varying the communication cost depending on the
00050 //   distance between processors (ie. all processors are equally far apart)
00051 //   and it assumes that the effective cost of communicating between two
00052 //   boxes on the same processor is zero.  The communication workload is
00053 //   represented as a graph.
00054 //
00055 //  ********************************************************
00056 //  CAVEAT: the communication workload argument is not
00057 //           present in this version of the function.
00058 //  ********************************************************
00059 //
00060 //  The resulting assignment is an integer for each box in the hierarchy,
00061 //   which gives the processor number (starting at zero) on which each box
00062 //   should reside.  Again, represented as a Vector of Vectors.
00063 //
00064 //  The other output argument is the efficiency ratio, which is a measure
00065 //   of how close to perfect the final load balance is.  The \var{effRatio}
00066 //   output variable is defined as the smallest load on any processor divided
00067 //   by the largest load.  A perfect load balance has efficiency == 1.
00068 //
00069 //  ********************************************************
00070 //  CAVEAT: in this version, each level in the AMR hierarchy
00071 //          is balanced independently, so the efficiency ratio
00072 //          that is returned is the worst over all levels.
00073 //  ********************************************************
00074 //
00075 //  It is important to note that it is the sum of the computation cost 
00076 //   and communication cost that is balanced, so the values in the two
00077 //   variables must be in the same units.  It doesn't matter what the
00078 //   units are.
00079 //
00080 //  ********************************************************
00081 //  CAVEAT: the communication workload argument is not
00082 //           present in this version of the function.
00083 //  ********************************************************
00084 // 
00085 // Interface Specification:
00086 //  int LoadBalance() arguments are:
00087 //       Vector<Vector<int>>& procAssignments  //output: processor number 
00088 //                                             //   for each box
00089 //       Real&                effRatio         //output: efficiency ratio
00090 // const Vector<Vector<Box>>& Grids            //input: meshes to balance
00091 // const Vector<Vector<long>>&ComputeLoads     //input: computational cost
00092 //                                             //   of each box
00093 //###not used###
00094 //### const [...something...]&CommunicateLoads //input: communication cost
00095 //                                             //   between each pair of 
00096 //                                             //   neighboring boxes
00097 // const Vector<int>&         RefRatios        //input: refinement ratio
00098 //                                             //   for each level
00099 //
00100 // Returns: integer status_code
00101 //    =0  means succesful completion
00102 //  exceptions: (output variables are not defined)
00103 //  -1011 input vectors (\var{Grids} and \var{ComputeLoads}) are not
00104 //        the same size
00105 //  -1012 one of the vector elements of the input vectors (\var{Grids} 
00106 //        and \var{ComputeLoads}) are not the same size
00107 //  -1013 input vectors (\var{Grids} and \var{RefRatios}) are not
00108 //        the same size
00109 //
00110 // Modification History
00111 //  19Nov99 <dbs> initial design and coding
00112 //
00113 
00114 
00115 #ifndef _LOADBALANCE_H_
00116 #define _LOADBALANCE_H_
00117 
00118 #include "SPACE.H"
00119 #include "REAL.H"
00120 #include "Box.H"
00121 #include "Vector.H"
00122 #include "BoxLayout.H"
00123 #include "SPMD.H"
00124 
00125 int
00126 LoadBalance( Vector<Vector<int> >& procAssignments  //output: processor number  
00127 //                                                  //   for each box           
00128             ,Real&                 effRatio         //output: ratio of min load
00129 //                                                  //   to max load
00130      ,const Vector<Vector<Box> >&  Grids            //input: meshes to balance  
00131      ,const Vector<Vector<long> >& ComputeLoads     //input: computational cost 
00132 //                                                  //   of each box            
00133 //## ,const [...something...]&     CommunicateLoads //input: communication cost 
00134 //                                                  //   between each pair of   
00135 //                                                  //   neighboring boxes      
00136      ,const Vector<int>&           RefRatios        //input: refinement ratio   
00137 //                                                  //   for each level        
00138             ,int nProc = numProc()
00139            ) ;
00140 
00141 
00142 int
00143 LoadBalance( Vector<BoxLayout>&    Grids            //in-out: input grids to balance
00144 //                                                  //   and output proc. numbers
00145             ,Real&                 effRatio         //output: ratio of min load
00146 //                                                  //   to max load
00147      ,const Vector<Vector<long> >& ComputeLoads     //input: computational cost 
00148 //                                                  //   of each box            
00149 //## ,const [...something...]&     CommunicateLoads //input: communication cost 
00150 //                                                  //   between each pair of   
00151 //                                                  //   neighboring boxes      
00152      ,const Vector<int>&           RefRatios        //input: refinement ratio   
00153 //                                                  //   for each level         
00154             ,int nProc = numProc()
00155            ) ;
00157 
00159 int LoadBalance(Vector<int>& procAssignments, const Vector<Box>& boxes);
00160 
00161 #endif

Generated on Tue Jul 2 10:42:20 2002 for Chombo by doxygen1.2.16