Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members

LoadBalance.H

Go to the documentation of this file.
00001 /*   _______              __
00002     / ___/ /  ___  __ _  / /  ___
00003    / /__/ _ \/ _ \/  V \/ _ \/ _ \
00004    \___/_//_/\___/_/_/_/_.__/\___/
00005 */
00006 // CHOMBO Copyright (c) 2000-2004, The Regents of the University of
00007 // California, through Lawrence Berkeley National Laboratory (subject to
00008 // receipt of any required approvals from U.S. Dept. of Energy).  All
00009 // rights reserved.
00010 //
00011 // Redistribution and use in source and binary forms, with or without
00012 // modification, are permitted provided that the following conditions are met:
00013 //
00014 // (1) Redistributions of source code must retain the above copyright
00015 // notice, this list of conditions and the following disclaimer.
00016 // (2) Redistributions in binary form must reproduce the above copyright
00017 // notice, this list of conditions and the following disclaimer in the
00018 // documentation and/or other materials provided with the distribution.
00019 // (3) Neither the name of Lawrence Berkeley National Laboratory, U.S.
00020 // Dept. of Energy nor the names of its contributors may be used to endorse
00021 // or promote products derived from this software without specific prior
00022 // written permission.
00023 //
00024 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00025 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
00026 // TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
00027 // PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
00028 // OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00029 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00030 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00031 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00032 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00033 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00034 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00035 //
00036 // You are under no obligation whatsoever to provide any bug fixes,
00037 // patches, or upgrades to the features, functionality or performance of
00038 // the source code ("Enhancements") to anyone; however, if you choose to
00039 // make your Enhancements available either publicly, or directly to
00040 // Lawrence Berkeley National Laboratory, without imposing a separate
00041 // written license agreement for such Enhancements, then you hereby grant
00042 // the following license: a non-exclusive, royalty-free perpetual license
00043 // to install, use, modify, prepare derivative works, incorporate into
00044 // other computer software, distribute, and sublicense such Enhancements or
00045 // derivative works thereof, in binary and source code form.
00046 //
00047 // TRADEMARKS. Product and company names mentioned herein may be the
00048 // trademarks of their respective owners.  Any rights not expressly granted
00049 // herein are reserved.
00050 //
00051 
00052 // Purpose:
00053 //  LoadBalance() is a global function to compute an assignment
00054 //  of boxes to processors for an AMR mesh hierarchy.  The assignment
00055 //  is made so as to balance the computation and communication
00056 //  workload on each processor (i.e. make it as even as possible).
00057 //
00058 //  ********************************************************
00059 //  CAVEAT: this version ignores the communication workload.
00060 //          It balances ONLY the compute workload.
00061 //  ********************************************************
00062 //
00063 // Usage:
00064 //  The meshes in the AMR hierarchy are represented using
00065 //   a Vector of Vectors of Boxes.
00066 //
00067 //  The computational workload is a real number for each box in the
00068 //   hierarchy, also represented as a Vector of Vectors.
00069 //
00070 //  The communication workload is a real number for each connection
00071 //   between pairs of boxes, which specifies the cost of communication
00072 //   between the two boxes if they are on different processors.  No
00073 //   allowance is made for varying the communication cost depending on the
00074 //   distance between processors (ie. all processors are equally far apart)
00075 //   and it assumes that the effective cost of communicating between two
00076 //   boxes on the same processor is zero.  The communication workload is
00077 //   represented as a graph.
00078 //
00079 //  ********************************************************
00080 //  CAVEAT: the communication workload argument is not
00081 //           present in this version of the function.
00082 //  ********************************************************
00083 //
00084 //  The resulting assignment is an integer for each box in the hierarchy,
00085 //   which gives the processor number (starting at zero) on which each box
00086 //   should reside.  Again, represented as a Vector of Vectors.
00087 //
00088 //  The other output argument is the efficiency ratio, which is a measure
00089 //   of how close to perfect the final load balance is.  The \var{effRatio}
00090 //   output variable is defined as the smallest load on any processor divided
00091 //   by the largest load.  A perfect load balance has efficiency == 1.
00092 //
00093 //  ********************************************************
00094 //  CAVEAT: in this version, each level in the AMR hierarchy
00095 //          is balanced independently, so the efficiency ratio
00096 //          that is returned is the worst over all levels.
00097 //  ********************************************************
00098 //
00099 //  It is important to note that it is the sum of the computation cost
00100 //   and communication cost that is balanced, so the values in the two
00101 //   variables must be in the same units.  It doesn't matter what the
00102 //   units are.
00103 //
00104 //  ********************************************************
00105 //  CAVEAT: the communication workload argument is not
00106 //           present in this version of the function.
00107 //  ********************************************************
00108 //
00109 // Interface Specification:
00110 //  int LoadBalance() arguments are:
00111 //       Vector<Vector<int>>& procAssignments  //output: processor number
00112 //                                             //   for each box
00113 //       Real&                effRatio         //output: efficiency ratio
00114 // const Vector<Vector<Box>>& Grids            //input: meshes to balance
00115 // const Vector<Vector<long>>&ComputeLoads     //input: computational cost
00116 //                                             //   of each box
00117 //###not used###
00118 //### const [...something...]&CommunicateLoads //input: communication cost
00119 //                                             //   between each pair of
00120 //                                             //   neighboring boxes
00121 // const Vector<int>&         RefRatios        //input: refinement ratio
00122 //                                             //   for each level
00123 //
00124 // Returns: integer status_code
00125 //    =0  means succesful completion
00126 //  exceptions: (output variables are not defined)
00127 //  -1011 input vectors (\var{Grids} and \var{ComputeLoads}) are not
00128 //        the same size
00129 //  -1012 one of the vector elements of the input vectors (\var{Grids}
00130 //        and \var{ComputeLoads}) are not the same size
00131 //  -1013 input vectors (\var{Grids} and \var{RefRatios}) are not
00132 //        the same size
00133 //
00134 // Modification History
00135 //  19Nov99 <dbs> initial design and coding
00136 //
00137 
00138 #ifndef _LOADBALANCE_H_
00139 #define _LOADBALANCE_H_
00140 
00141 #include "SPACE.H"
00142 #include "REAL.H"
00143 #include "Box.H"
00144 #include "Vector.H"
00145 #include "BoxLayout.H"
00146 #include "SPMD.H"
00147 
00149 
00156 int
00157 LoadBalance( Vector<Vector<int> >&         a_procAssignments
00158              ,Real&                        a_effRatio
00159              ,const Vector<Vector<Box> >&  a_Grids
00160              ,const Vector<Vector<long> >& a_ComputeLoads
00161              ,const Vector<int>&           a_RefRatios
00162              ,int a_nProc = numProc()
00163              ) ;
00164 
00166 
00173 int
00174 LoadBalance( Vector<BoxLayout>&    Grids
00175              ,Real&                 effRatio
00176              ,const Vector<Vector<long> >& ComputeLoads
00177              ,const Vector<int>&           RefRatios
00178              ,int nProc = numProc()
00179              ) ;
00180 
00182 
00184 int LoadBalance(Vector<int>& procAssignments, const Vector<Box>& boxes,
00185                 int a_numProc = numProc());
00186 
00188 
00190 int LoadBalance(Vector<int>&        procAssignments,
00191                 const Vector<long>& a_computeLoads,
00192                 const Vector<Box>&  a_boxes,
00193                 const int a_numProc = numProc());
00194 
00196 int
00197 LoadBalance(Vector<int>& procAssignments
00198             ,Real&                 effRatio
00199             ,const Vector<Box>&  Grids
00200             ,const Vector<long>& ComputeLoads);
00201 
00202 #endif

Generated on Wed Oct 5 13:52:09 2005 for Chombo&AMRSelfGravity by  doxygen 1.4.1