You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
228 lines
12 KiB
228 lines
12 KiB
<!-------- @HEADER
|
|
!
|
|
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!
|
|
! Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
|
|
! Copyright 2012 Sandia Corporation
|
|
!
|
|
! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
|
|
! the U.S. Government retains certain rights in this software.
|
|
!
|
|
! Redistribution and use in source and binary forms, with or without
|
|
! modification, are permitted provided that the following conditions are
|
|
! met:
|
|
!
|
|
! 1. Redistributions of source code must retain the above copyright
|
|
! notice, this list of conditions and the following disclaimer.
|
|
!
|
|
! 2. Redistributions in binary form must reproduce the above copyright
|
|
! notice, this list of conditions and the following disclaimer in the
|
|
! documentation and/or other materials provided with the distribution.
|
|
!
|
|
! 3. Neither the name of the Corporation nor the names of the
|
|
! contributors may be used to endorse or promote products derived from
|
|
! this software without specific prior written permission.
|
|
!
|
|
! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
|
|
! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
|
|
! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
!
|
|
! Questions? Contact Karen Devine kddevin@sandia.gov
|
|
! Erik Boman egboman@sandia.gov
|
|
!
|
|
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!
|
|
! @HEADER
|
|
------->
|
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
|
|
<meta name="sandia.approved" content="SAND99-1376">
|
|
<meta name="author" content="karen devine, kddevin@sandia.gov">
|
|
<title> Zoltan Developer's Guide: Adding Data Structures</title>
|
|
|
|
</head>
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>
|
|
| <a href="dev_add_memory.html">Next</a> | <a href="dev_add_lb.html">Previous</a></i></b></div>
|
|
|
|
<h2>
|
|
<a NAME="new_data_structs"></a>Data Structures</h2>
|
|
The main data structures for the algorithm should be pointed to by the
|
|
<i>LB.Data_Structure</i>
|
|
field of the <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>.
|
|
This requirement allows reuse of data structures from one invocation of
|
|
the new load-balancing algorithm to the next. It also prevents the use
|
|
of global data structures for the algorithm so that multiple instances
|
|
of the algorithm may be used (i.e., the same algorithm can be used for
|
|
multiple <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b> structures).
|
|
An example showing the construction of data structures for the
|
|
<a href="../ug_html/ug_alg_rcb.html">Recursive
|
|
Coordinate Bisection (RCB)</a> algorithm is included
|
|
in the <a href="#RCB_example">figure</a> below.
|
|
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
|
|
<tr>
|
|
<td><a NAME="RCB_example"></a>
|
|
<tt>
|
|
<br>/* Allocate RCB data structure for this Zoltan structure.
|
|
<br> * If the previous data structure still exists, free the Dots
|
|
first;
|
|
<br> * the other fields can be reused.
|
|
<br> */
|
|
<br>if (zz->LB.Data_Structure == NULL) {
|
|
<br> rcb = (RCB_STRUCT *) <a href="../ug_html/ug_util_mem.html#Zoltan_Malloc">ZOLTAN_MALLOC</a>(sizeof(RCB_STRUCT));
|
|
<br> zz->LB.Data_Structure = (void *) rcb;
|
|
<br> rcb->Tree_Ptr = (struct rcb_tree *)
|
|
<br>
|
|
<a href="../ug_html/ug_util_mem.html#Zoltan_Malloc">ZOLTAN_MALLOC</a>(zz->Num_Proc*sizeof(struct
|
|
rcb_tree));
|
|
<br> rcb->Box = (struct rcb_box *) <a href="../ug_html/ug_util_mem.html#Zoltan_Malloc">ZOLTAN_MALLOC</a>(sizeof(struct
|
|
rcb_box));
|
|
<br>}
|
|
<br>else {
|
|
<br> rcb = (RCB_STRUCT *) zz->LB.Data_Structure;
|
|
<br> <a href="../ug_html/ug_util_mem.html#Zoltan_Free">ZOLTAN_FREE</a>(&(rcb->Dots));
|
|
<br>}
|
|
</tt>
|
|
</td>
|
|
</tr>
|
|
|
|
<caption ALIGN=BOTTOM><i>Example demonstrating allocation of data structures
|
|
for the RCB algorithm. (Taken from rcb/rcb_util.c.)</i></caption>
|
|
</table></center>
|
|
|
|
<p>The data needed for the algorithm is collected through calls to the
|
|
query functions registered by the application. Algorithms should test the
|
|
query function pointers for NULL and report errors when needed functions
|
|
are not registered. The appropriate query functions can be called to build
|
|
the algorithm's data structures up front, or they can be called during
|
|
the algorithm's execution to gather data only as it is needed. The <a href="#query_example">figure</a>
|
|
below shows how the <i>Dots</i> data structure needed by RCB is built.
|
|
The call to <i>zz->Get_Num_Obj</i> invokes an <b><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b>
|
|
query function to determine the number of objects on the processor.
|
|
Space for the <i>Dots</i> data structure is allocated through calls to
|
|
<b><a href="../ug_html/ug_util_mem.html#Zoltan_Malloc">ZOLTAN_MALLOC</a></b>, <a href="dev_lb_types.html#ID alloc"><b>ZOLTAN_MALLOC_GID_ARRAY</b></a>,
|
|
and <a href="dev_lb_types.html#ID alloc"><b>ZOLTAN_MALLOC_LID_ARRAY</b></a>. The <i>Dots</i> information is obtained
|
|
through a call to the Zoltan service function <b><a href="dev_services_objlist.html">Zoltan_Get_Obj_List</a></b>; this
|
|
function calls either an <b><a href="../ug_html/ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
|
|
or an <b><a href="../ug_html/ug_query_lb.html#ZOLTAN_FIRST_OBJ_FN">ZOLTAN_FIRST_OBJ_FN</a></b>/<b><a href="../ug_html/ug_query_lb.html#ZOLTAN_NEXT_OBJ_FN">ZOLTAN_NEXT_OBJ_FN</a></b>
|
|
pair to get the object IDs and weights. The data for each
|
|
<i>Dot</i> is
|
|
set in the function <i>initialize_dot</i>, which includes calls to<i> zz->Get_Geom</i>,
|
|
an <b><a href="../ug_html/ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
|
|
query function.
|
|
<br>
|
|
<br>
|
|
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
|
|
<tr>
|
|
<td><a NAME="query_example"></a>
|
|
<tt>
|
|
<br>/*
|
|
<br> * Allocate space for objects. Allow extra space
|
|
<br> * for objects that are imported to the processor.
|
|
<br> */
|
|
<p>*num_obj = zz->Get_Num_Obj(zz->Get_Num_Obj_Data, &ierr);
|
|
<br>if (ierr) {
|
|
<br> <a href="dev_intro_coding.html#ZOLTAN_PRINT">ZOLTAN_PRINT_ERROR</a>(zz->Proc,
|
|
yo,
|
|
<br>
|
|
"Error returned from Get_Num_Obj.");
|
|
<br> return(ierr);
|
|
<br>}
|
|
<p>*max_obj = (int)(1.5 * *num_obj) + 1;
|
|
<br>*global_ids = <a href="dev_lb_types.html#ID alloc">ZOLTAN_MALLOC_GID_ARRAY</a>(zz, (*max_obj));
|
|
<br>*local_ids = <a href="dev_lb_types.html#ID alloc">ZOLTAN_MALLOC_LID_ARRAY</a>(zz, (*max_obj));
|
|
<br>*dots = (struct Dot_Struct *)
|
|
<br> <a href="../ug_html/ug_util_mem.html#Zoltan_Malloc">ZOLTAN_MALLOC</a>((*max_obj)*sizeof(struct
|
|
Dot_Struct));
|
|
<p>if (!(*global_ids) || (zz->Num_LID && !(*local_ids)) ||
|
|
!(*dots)) {
|
|
<br> <a href="dev_intro_coding.html#ZOLTAN_PRINT">ZOLTAN_PRINT_ERROR</a>(zz->Proc,
|
|
yo, "Insufficient memory.");
|
|
<br> return(<a href="../ug_html/ug_interface.html#Error Codes">ZOLTAN_MEMERR</a>);
|
|
<br>}
|
|
<p>if (*num_obj > 0) {
|
|
<p> if (wgtflag) {
|
|
<p> /*
|
|
<br> * Allocate space for object weights.
|
|
<br> */
|
|
<p> objs_wgt = (float *) <a href="../ug_html/ug_util_mem.html#Zoltan_Malloc">ZOLTAN_MALLOC</a>((*num_obj)*sizeof(float));
|
|
<br> if (!objs_wgt) {
|
|
<br> <a href="dev_intro_coding.html#ZOLTAN_PRINT">ZOLTAN_PRINT_ERROR</a>(zz->Proc,
|
|
yo, "Insufficient memory.");
|
|
<br> return(<a href="../ug_html/ug_interface.html#Error Codes">ZOLTAN_MEMERR</a>);
|
|
<br> }
|
|
<br> for (i = 0; i < *num_obj; i++) objs_wgt[i]
|
|
= 0.;
|
|
<br> }
|
|
<p> /*
|
|
<br> * Get list of objects' IDs and weights.
|
|
<br> */
|
|
<p> <a href="dev_services_objlist.html">Zoltan_Get_Obj_List</a>(zz, *global_ids, *local_ids, wgtflag,
|
|
<br> objs_wgt, &ierr);
|
|
<br> if (ierr) {
|
|
<br> <a href="dev_intro_coding.html#ZOLTAN_PRINT">ZOLTAN_PRINT_ERROR</a>(zz->Proc,
|
|
yo,
|
|
<br>
|
|
"Error returned from Zoltan_Get_Obj_List.");
|
|
<br> <a href="../ug_html/ug_util_mem.html#Zoltan_Free">ZOLTAN_FREE</a>(&objs_wgt);
|
|
<br> return(ierr);
|
|
<br> }
|
|
<p> ierr = initialize_dot(zz, *global_ids, *local_ids, *dots,
|
|
<br>
|
|
*num_obj, wgtflag, objs_wgt);
|
|
<br> if (ierr == ZOLTAN_FATAL || ierr == ZOLTAN_MEMERR) {
|
|
<br> <a href="dev_intro_coding.html#ZOLTAN_PRINT">ZOLTAN_PRINT_ERROR</a>(zz->Proc,
|
|
yo,
|
|
<br>
|
|
"Error returned from initialize_dot.");
|
|
<br> <a href="../ug_html/ug_util_mem.html#Zoltan_Free">ZOLTAN_FREE</a>(&objs_wgt);
|
|
<br> return(ierr);
|
|
<br> }
|
|
<p> <a href="../ug_html/ug_util_mem.html#Zoltan_Free">ZOLTAN_FREE</a>(&objs_wgt);
|
|
<br>}
|
|
</tt>
|
|
</td>
|
|
</tr>
|
|
|
|
<caption ALIGN=BOTTOM><i>Example demonstrating how data structures are
|
|
built for the RCB algorithm. (Taken from rcb/shared.c.)</i></caption>
|
|
</table></center>
|
|
|
|
<p>
|
|
The data structures pointed to by <i>zz->LB.Data_Structure</i> will be freed
|
|
at some point, and may be copied.
|
|
<p>A function that frees these structures and resets <i>zz->LB.Data_Structure</i>
|
|
to NULL should be written. The function should be called when the load-balancing
|
|
algorithm exits, either normally or due to an error condition.
|
|
The function
|
|
<b>Zoltan_RCB_Free_Structure</b> in <i>rcb/rcb_util.c</i> may be used as an example.
|
|
<A NAME="Copy"></A>
|
|
<p>If your algorithm uses the <a href="../ug_html/ug_alg_rcb.html">KEEP_CUTS</a>
|
|
parameter, a function that copies one <i>zz->LB.Data_Structure</i> to another is
|
|
required. This is particularly important for C++,
|
|
which may create temporary objects
|
|
at runtime by invoking a copy operator (which will call your copy function).
|
|
It is a convenience for C applications, which may wish to copy one Zoltan_Struct
|
|
to another.
|
|
See the function <b>Zoltan_RCB_Copy_Structure</b> in <i>rcb/rcb_util.c</i>
|
|
for an example.
|
|
|
|
<hr WIDTH="100%">
|
|
<br>[<a href="dev.html">Table of Contents</a> | <a href="dev_add_memory.html">Next:
|
|
Memory Management</a> | <a href="dev_add_lb.html">Previous:
|
|
Load-Balancing Function Implementation</a> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
|
|
<br>
|
|
</body>
|
|
</html>
|
|
|