xfygogo/phasicFlow
1
0
Fork 0
mirror of https://github.com/PhasicFlow/phasicFlow.git synced 2025-06-12 16:26:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

Zoltan is added as thirdParty package

Browse Source
This commit is contained in:
Hamidreza
2025-05-15 21:58:43 +03:30
parent 83a6e4baa1
commit d7479cf1bd
3392 changed files with 318142 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
thirdParty/Zoltan/docs/dev_html/brack3d.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

409
thirdParty/Zoltan/docs/dev_html/dev.html vendored Normal file
View File

@ -0,0 +1,409 @@
<!-------- @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="filename" content="Zoltan.html">
<meta name="review" content="28 May, 1999">
<meta name="subject" content="Zoltan Developer's Guide">
<meta name="sandia.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2006-2955">
<meta name="sandia.create_date" content="05/28/99">
<meta name="keywords" content="Zoltan, Zoltan Developer's Guide, Zoltan dynamic load balancing library, Zoltan parallel computing">
<meta name="description" content="Zoltan: Developer's Guide for the Zoltan Library project at Sandia National Laboratories">
<meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
<title>Zoltan Developer's Guide</title>
<!----CHANGE INFORMATION IN AREAS WITH THIS HEADER---->
<!----SCROLL DOWN TO FIND OTHER AREAS TO BE CHANGED---->
<!--------CHANGE THE NAME AFTER THE DASH-------->
<!--------CHANGE THE FILENAME-------->
<!--------CHANGE THE REVIEW DATE-------->
<!--------CHANGE THE SUBJECT-------->
<link rel="schema.sandia" href="https://www.sandia.gov/html_schema.htm">
<!--------CHANGE THE SAND NUMBER INFO-------->
<!--------INSERT THE DATE DOCUMENT CREATED-------->
<!--------CHANGE THE PAGE OWNER AND EMAIL ADDRESS-------->
<link rev="made" title="name of contact" >
<!--------CHANGE THE PAGE MAKER AND EMAIL ADDRESS-------->
<!--------PLACE FIVE KEY WORDS WITHIN THE QUOTES-------->
<!---------------END OF THIS CHANGE AREA--------------->
</head>
<body text="#000000">
<!-- KDD Turned off alternative link colors in template; the >
<!-- following line was part of the above body command. >
<!-- link="#003366" vlink="#cc0033" alink="#000000">
<a NAME="TOP"></a><!---TOP BANNER AREA STARTS HERE--->
<table BORDER=0 valign="top" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="160" BGCOLOR="#003366">
<table BORDER=0 WIDTH="160" valign="top" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="160"><!--SANDIA LOGO AT TOP LEFT-->
<a href="https://www.sandia.gov/Main.html"><img SRC="https://www.sandia.gov/images/snlstkdc.gif" ALT="[Sandia National Laboratories]" BORDER=0 valign="top" height=49 width=126></a>
<p><img ISMAP SRC="https://www.sandia.gov/images/labelNEW.gif" ALT="[navigation panel]" HSPACE=2 BORDER=0 usemap="#shortMap" height=119 width=111></td>
<td><img SRC="https://www.sandia.gov/images/1pixel.gif" BORDER=0 height=1 width=10></td>
</tr>
</table>
<table BORDER=0 WIDTH="160" valign="top" >
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 0th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan.html">Zoltan
Home Page</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 1st little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td><b><font face="Verdana, Arial, Helvetica"><a href="../ug_html/ug.html">Zoltan
User's Guide</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 2nd little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td><b><font face="Verdana, Arial, Helvetica"><a href="dev.html">Zoltan
Developer's Guide</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 2A-nd little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan_FAQ.html">
Frequently Asked Questions</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 3rd little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan_phil.html">Zoltan
Project Description</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 4th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan_pubs.html">Papers
and Presentations</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 4Ath little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan_cite.html">How to Cite Zoltan</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 5th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica"><a href="https://github.com/sandialabs/Zoltan">Download
Zoltan</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 6th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan_bugreport.html">Report a Zoltan Bug</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 7th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica">
<a href="mailto: zoltan-dev@software.sandia.gov">Contact Zoltan Developers</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 8th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica">
<a href="https://www.sandia.gov/general/privacy-security/index.html">Sandia Privacy and Security Notice</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
</table>
</td>
<td VALIGN=TOP>
<!--MAIN CONTENT AREA STARTS HERE-->
<!----------------THIS IS A CHANGE AREA---------------->
<!------HEADER TEXT SHOULD BE REPLACE THIS TEXT------>
<b><font face="Verdana, Arial, Helvetica"><font size=+2>
Zoltan:
</font></font></b>
<br>
<b><font face="Verdana, Arial, Helvetica"><font size=+2>
Parallel Partitioning, Load Balancing and
Data-Management Services
</font></font></b>
<p>
<!---------------END OF THIS CHANGE AREA--------------->
<!----------------THIS IS A CHANGE AREA---------------->
<!--MAIN CONTENT SHOULD BE PLACED IN THE AREA BELOW-->
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<p><b><font face="Verdana, Arial, Helvetica"><font size=+2>Developer's
Guide&nbsp;</font></font></b>
<p>
<hr WIDTH="100%">
<p>
<hr WIDTH="100%">
<p>
<h3><b> The Zoltan Team </b></h3>
<table width="100%">
<tr>
<td width="50%" valign=top>
<b> Sandia National Laboratories</b><br>
<a href="https://www.sandia.gov/~egboman">Erik Boman</a> <br>
Cedric Chevalier<br>
<a href="https://www.sandia.gov/~kddevin">Karen Devine</a><br>
Vitus Leung<br>
Sivasankaran Rajamanickam<br>
Lee Ann Riesen<br>
Michael Wolf<br>
</td>
<td width="50%" valign=top>
<b> Ohio State University</b><br>
<a href="https://bmi.osu.edu/~umit/">Umit Catalyurek</a><br>
<a href="https://www.ece.osu.edu/~bozdagd">Doruk Bozdag</a><br>
</td>
</tr>
</table>
<br>
<h3><b> Past Zoltan Contributors</b></h3>
<table width="100%"
<tr>
<td width="50%" valign=top>
<b> Sandia National Laboratories: </b><br>
Robert Heaphy<br>
Bruce Hendrickson <br>
Matthew St. John<br>
Courtenay Vaughan<br>
<br>
</td>
<td width="50%" valign=top>
<b> Williams College</b><br>
<a href="https://www.teresco.org/~terescoj/">James Teresco</a><br>
</td>
</tr>
<tr>
<td width="50%" valign=top>
<b> National Institute of Standards and Technology</b><br>
<a href="https://math.nist.gov/~mitchell">William F. Mitchell</a><br>
</td>
<td width="50%" valign=top>
<b> Rensselaer Polytechnic Institute</b><br>
Jamal Faik<br>
Luis Gervasio<br>
</td>
</tr>
</table>
<p>
<p>
<hr WIDTH="100%">
<div ALIGN=right>
<b><i>Zoltan Developer's Guide, Version 3.3</b></i></div>
<p>
<p>
<blockquote>
<b>
The Zoltan Developer's Guide is undergoing major revision and will be re-released with Zoltan 4.0.
Please excuse the inconvenience.
</b>
</blockquote>
<!-------- To Zoltan developers: The former version of dev.html is in devOLD.html. -------->
<hr WIDTH="100%">
Copyright (c) 2000-2012, Sandia National Laboratories. <br>
<hr WIDTH="100%">
<!-------- To Zoltan developers: Can reactivate these links when revise guide.
<br>[<a href="../Zoltan.html">Zoltan Home Page</a>&nbsp; |&nbsp; <a href="dev_intro.html">Next:&nbsp;
Introduction and General Principles</a>]&nbsp; ------>
<!---------MAIN CONTENT AREA ENDS HERE---------><!-- CHANGE CONTACT + E-MAIL, NOTE "SUBJECT" IN E-MAIL CODE --></td>
</tr>
</table>
<!<hr width="100%">
<!--Image maps below-->
<map name="shortMap">
<area shape="rect" coords="2,2,108,14"href="https://www.sandia.gov/about/index.html"></area>
<area shape="rect" coords="2,19,108,31"href="https://www.sandia.gov/mission/ste/index.html"></area>
<area shape="rect" coords="2,36,108,48"href="https://www.sandia.gov/mission/index.html"></area>
<area shape="rect" coords="2,53,108,65"href="https://www.sandia.gov/contact-us/index.html"></area>
<area shape="rect" coords="2,70,108,82"href="https://www.sandia.gov/news/index.html"></area>
<area shape="rect" coords="2,87,108,99"href="https://www.sandia.gov/search/index.html"></area>
<area shape="rect" coords="2,104,108,116"href="https://www.sandia.gov/Main.html"></area>
</map>
<!----------------THIS IS A CHANGE AREA---------------->
<!----NAME AND DATE OF LAST REVISION SHOULD BE HERE---->
<!---------------END OF THIS CHANGE AREA--------------->
</body>
</html>

506
thirdParty/Zoltan/docs/dev_html/devOLD.html vendored Normal file
View File

@ -0,0 +1,506 @@
<!-------- @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="filename" content="Zoltan.html">
<meta name="review" content="28 May, 1999">
<meta name="subject" content="Zoltan Developer's Guide">
<meta name="sandia.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2006-2955">
<meta name="sandia.create_date" content="05/28/99">
<meta name="keywords" content="Zoltan, Zoltan Developer's Guide, Zoltan dynamic load balancing library, Zoltan parallel computing">
<meta name="description" content="Zoltan: Developer's Guide for the Zoltan Library project at Sandia National Laboratories">
<meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
<title>Zoltan Developer's Guide</title>
<!----CHANGE INFORMATION IN AREAS WITH THIS HEADER---->
<!----SCROLL DOWN TO FIND OTHER AREAS TO BE CHANGED---->
<!--------CHANGE THE NAME AFTER THE DASH-------->
<!--------CHANGE THE FILENAME-------->
<!--------CHANGE THE REVIEW DATE-------->
<!--------CHANGE THE SUBJECT-------->
<link rel="schema.sandia" href="http://www.sandia.gov/html_schema.htm">
<!--------CHANGE THE SAND NUMBER INFO-------->
<!--------INSERT THE DATE DOCUMENT CREATED-------->
<!--------CHANGE THE PAGE OWNER AND EMAIL ADDRESS-------->
<link rev="made" title="name of contact" >
<!--------CHANGE THE PAGE MAKER AND EMAIL ADDRESS-------->
<!--------PLACE FIVE KEY WORDS WITHIN THE QUOTES-------->
<!---------------END OF THIS CHANGE AREA--------------->
</head>
<body text="#000000">
<!-- KDD Turned off alternative link colors in template; the >
<!-- following line was part of the above body command. >
<!-- link="#003366" vlink="#cc0033" alink="#000000">
<a NAME="TOP"></a><!---TOP BANNER AREA STARTS HERE--->
<table BORDER=0 valign="top" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="160" BGCOLOR="#003366">
<table BORDER=0 WIDTH="160" valign="top" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="160"><!--SANDIA LOGO AT TOP LEFT-->
<a href="http://www.sandia.gov/Main.html"><img SRC="http://www.sandia.gov/images/snlstkdc.gif" ALT="[Sandia National Laboratories]" BORDER=0 valign="top" height=49 width=126></a>
<p><img ISMAP SRC="http://www.sandia.gov/images/labelNEW.gif" ALT="[navigation panel]" HSPACE=2 BORDER=0 usemap="#shortMap" height=119 width=111></td>
<td><img SRC="http://www.sandia.gov/images/1pixel.gif" BORDER=0 height=1 width=10></td>
</tr>
</table>
<table BORDER=0 WIDTH="160" valign="top" >
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 0th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan.html">Zoltan
Home Page</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 1st little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td><b><font face="Verdana, Arial, Helvetica"><a href="../ug_html/ug.html">Zoltan
User's Guide</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 2nd little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td><b><font face="Verdana, Arial, Helvetica"><a href="dev.html">Zoltan
Developer's Guide</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 2A-nd little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan_FAQ.html">
Frequently Asked Questions</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 3rd little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan_phil.html">Zoltan
Project Description</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 4th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan_pubs.html">Papers
and Presentations</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 4Ath little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan_cite.html">How to Cite Zoltan</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 5th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica"><a href="http://www.cs.sandia.gov/~web1400/1400_download.html">Download
Zoltan</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 6th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica"><a href="../Zoltan_bugreport.html">Report a Zoltan Bug</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 7th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica">
<a href="mailto: zoltan-dev@software.sandia.gov">Contact Zoltan Developers</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
<tr ALIGN=LEFT VALIGN=TOP>
<td VALIGN=TOP WIDTH="150"><!----------- 8th little turquoise bevel button ------------>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="150" BGCOLOR="#00CCFF" >
<tr ALIGN=CENTER VALIGN=CENTER>
<td COLSPAN="2"><b><font face="Verdana, Arial, Helvetica">
<a href="http://www.sandia.gov/general/privacy-security/index.html">Sandia Privacy and Security Notice</a></font></b></td>
</tr>
</table>
</td>
<td VALIGN=TOP WIDTH="20"></td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2"></td>
</tr>
<!-------------------------------------------------------------------------->
</table>
</td>
<td VALIGN=TOP>
<!--MAIN CONTENT AREA STARTS HERE-->
<!----------------THIS IS A CHANGE AREA---------------->
<!------HEADER TEXT SHOULD BE REPLACE THIS TEXT------>
<b><font face="Verdana, Arial, Helvetica"><font size=+2>
Zoltan:
</font></font></b>
<br>
<b><font face="Verdana, Arial, Helvetica"><font size=+2>
Parallel Partitioning, Load Balancing and
Data-Management Services
</font></font></b>
<p>
<!---------------END OF THIS CHANGE AREA--------------->
<!----------------THIS IS A CHANGE AREA---------------->
<!--MAIN CONTENT SHOULD BE PLACED IN THE AREA BELOW-->
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<p><b><font face="Verdana, Arial, Helvetica"><font size=+2>Developer's
Guide&nbsp;</font></font></b>
<p>
<hr WIDTH="100%">
<p>
<hr WIDTH="100%">
<p>
<h3><b> The Zoltan Team </b></h3>
<table width="100%">
<tr>
<td width="50%" valign=top>
<b> Sandia National Laboratories</b><br>
<a href="http://www.sandia.gov/~egboman">Erik Boman</a> <br>
Cedric Chevalier<br>
<a href="http://www.cs.sandia.gov/~kddevin">Karen Devine</a><br>
Vitus Leung<br>
Lee Ann Riesen<br>
</td>
<td width="50%" valign=top>
<b> Ohio State University</b><br>
<a href="http://bmi.osu.edu/~umit/">Umit Catalyurek</a><br>
<a href="http://www.ece.osu.edu/~bozdagd">Doruk Bozdag</a><br>
</td>
</tr>
</table>
<br>
<h3><b> Past Zoltan Contributors</b></h3>
<table width="100%"
<tr>
<td width="50%" valign=top>
<b> Sandia National Laboratories: </b><br>
Robert Heaphy<br>
<a href="http://www.cs.sandia.gov/~bahendr">Bruce Hendrickson</a></b><br>
Matthew St. John<br>
Courtenay Vaughan<br>
<br>
</td>
<td width="50%" valign=top>
<b> Williams College</b><br>
<a href="http://www.teresco.org/~terescoj/">James Teresco</a><br>
</td>
</tr>
<tr>
<td width="50%" valign=top>
<b> National Institute of Standards and Technology</b><br>
<a href="http://math.nist.gov/~mitchell">William F. Mitchell</a><br>
</td>
<td width="50%" valign=top>
<b> Rensselaer Polytechnic Institute</b><br>
Jamal Faik<br>
Luis Gervasio<br>
</td>
</tr>
</table>
<p>
<p>
<hr WIDTH="100%">
<div ALIGN=right>
<b><i>Zoltan Developer's Guide, Version 3.2</b></i></div>
<p>
<h4>
<table border="1"> <tr> <td>
<a href="http://www.cs.sandia.gov/~kddevin/Zoltan_pdf/dev.pdf">DOWNLOAD PDF VERSION HERE.</a>
</td> </tr> </table>
<p>
<h4>
<a href="dev_intro.html">Introduction and General Principles</a></h4>
<blockquote><a href="dev_intro_philosophy.html">Philosophy of Zoltan</a>
<br><a href="dev_intro_coding.html">Coding Principles in Zoltan</a>
<ol TYPE=A><a href="dev_intro_coding.html#include">Include files</a>
<br><a href="dev_intro_coding.html#global">Global Variables</a>
<br><a href="dev_intro_coding.html#functions">Function Names</a>
<br><a href="dev_intro_coding.html#par_comm">Parallel Communication</a>
<br><a href="dev_intro_coding.html#memory1">Memory Management</a>
<br><a href="dev_intro_coding.html#return">Errors, Warnings and Return Codes</a>
</ol>
<a href="dev_intro_sqe.html">Zoltan Quality Assurance</a>
</blockquote>
<h4>
<a href="dev_dist.html">Zoltan Distribution</a></h4>
<ol TYPE=1><a href="dev_dist_cvs.html">CVS</a>
<br><a href="dev_dist_dir.html">Layout of Directories</a>
<br><a href="dev_dist_compile.html">Compilation and Makefiles</a></ol>
<h4>
<a href="dev_lb.html">Zoltan Interface and Data Structures</a></h4>
<ol TYPE=1><a href="dev_lb_interface.html">Interface Functions</a>
<br><a href="dev_lb_types.html">ID Data Types</a>
<br><a href="dev_lb_structs.html">Data Structures</a></ol>
<h4>
<a href="dev_services.html">Services (to simplify new algorithm development)</a></h4>
<ol TYPE=1><a href="dev_services_params.html">Parameter Setting Routines</a>
<br><a href="dev_services_parallel.html">Parallel Computing Routines</a>
<br><a href="dev_services_objlist.html">Common Functions for Querying Applications</a>
<br><a href="dev_services_hash.html">Hash Function</a>
<br><a href="dev_services_time.html">Timing Routines</a>
<br><a href="dev_services_zoltantimer.html">High-Level Timing Services: ZOLTAN_TIMER</a>
<br><a href="dev_services_debug.html">Debugging Services</a></ol>
<h4>
<a href="dev_add.html">Adding New Load-Balancing Algorithms to Zoltan</a></h4>
<ol TYPE=1><a href="dev_add_interface.html">Load-Balancing Interface Routines</a>
<br><a href="dev_add_lb.html">Load-Balancing Function Implementation</a>
<br><a href="dev_add_struct.html">Data Structures</a>
<br><a href="dev_add_memory.html">Memory Management</a>
<br><a href="dev_add_params.html">Parameters</a>
<br><a href="dev_add_remap.html">Part Remapping</a>
</ol>
<h4>
<a href="dev_mig.html">Migration Tools</a></h4>
<h4>
<a href="dev_fortran.html">FORTRAN Interface</a></h4>
<h4>
<a href="dev_cpp.html">C++ Interface</a></h4>
<h4>
<a href="dev_refs.html">References</a></h4>
<h4>
<a href="dev_driver.html">Appendix: Using the Test Drivers <i>zdrive</i>, <i>zCPPdrive</i> and <i>zfdrive</i></a></h4>
<ul><a href="dev_driver.html#Introduction">Introduction</a>
<br><a href="dev_driver.html#running zdrive">Running the Test Drivers</a>
<br><a href="dev_driver.html#adding algorithms">Adding New Algorithms</a></ul>
<h4>
<a href="dev_view.html">Appendix: Visualization of Geometric Partitions</a></h4>
<ul><a href="dev_view.html#Vis_2D">2D problems with <I>gnuplot</I></a>
<br><a href="dev_view.html#Vis_3D">3D problems with <I>vtk_view</I></a>
<br><a href="dev_view.html#Vis_offscreen">Off-screen rendering with <I>vtk_write</I></a>
<br><a href="dev_view.html#Vis_other">Other file formats</a>
</ul>
<h4>
<a href="dev_test_script.html">Appendix: Using the Test Script <i>test_zoltan</i></a></h4>
<h4>
<a href="dev_rcb.html">Appendix: Recursive Coordinate Bisection (RCB)</a></h4>
<h4>
<a href="dev_rib.html">Appendix: Recursive Inertial Bisection (RIB)</a></h4>
<h4>
<a href="dev_parmetis.html">Appendix: Graph Partitioning (ParMETIS and Jostle) </a></h4>
<h4>
<a href="dev_phg.html">Appendix: Hypergraph Partitioning (PHG) </a></h4>
<h4>
<a href="dev_reftree.html">Appendix: Refinement Tree </a></h4>
<h4>
<a href="dev_hsfc.html">Appendix: Hilbert Space_Filling Curve (HSFC)</a></h4>
<h4>
<a href="dev_degenerate.html">Appendix: Handling Degenerate Geometries</a></h4>
<hr WIDTH="100%">
Copyright (c) 2000-2007, Sandia National Laboratories. <br>
<hr WIDTH="100%">
<br>[<a href="../Zoltan.html">Zoltan Home Page</a>&nbsp; |&nbsp; <a href="dev_intro.html">Next:&nbsp;
Introduction and General Principles</a>]&nbsp;<!---------MAIN CONTENT AREA ENDS HERE---------><!-- CHANGE CONTACT + E-MAIL, NOTE "SUBJECT" IN E-MAIL CODE --></td>
</tr>
</table>
<!<hr width="100%">
<!--Image maps below-->
<map name="shortMap">
<area shape="rect" coords="2,2,108,14"href="http://www.sandia.gov/about/index.html"></area>
<area shape="rect" coords="2,19,108,31"href="http://www.sandia.gov/mission/ste/index.html"></area>
<area shape="rect" coords="2,36,108,48"href="http://www.sandia.gov/mission/index.html"></area>
<area shape="rect" coords="2,53,108,65"href="http://www.sandia.gov/contact-us/index.html"></area>
<area shape="rect" coords="2,70,108,82"href="http://www.sandia.gov/news/index.html"></area>
<area shape="rect" coords="2,87,108,99"href="http://www.sandia.gov/search/index.html"></area>
<area shape="rect" coords="2,104,108,116"href="http://www.sandia.gov/Main.html"></area>
</map>
<!----------------THIS IS A CHANGE AREA---------------->
<!----NAME AND DATE OF LAST REVISION SHOULD BE HERE---->
<!---------------END OF THIS CHANGE AREA--------------->
</body>
</html>

127
thirdParty/Zoltan/docs/dev_html/dev_add.html vendored Normal file
View File

@ -0,0 +1,127 @@
<!-------- @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.6 sun4m) [Netscape]">
<meta name="sandia.approved" content="SAND99-1376">
<meta name="author" content="karen devine, kddevin@sandia.gov">
<title> Zoltan Developer's Guide: Adding Algorithms</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_add_interface.html">Next</a>&nbsp; |&nbsp; <a href="dev_services_debug.html">Previous</a></i></b></div>
<h2>
<a NAME="new_methods"></a>Adding New Load-Balancing Algorithms to Zoltan</h2>
The Zoltan library is designed so that adding new load-balancing algorithms
to the library is simple. In many cases, existing code can be easily modified
to use the interface query functions to build the data structures needed
for the algorithm. The process for adding new algorithms to the library
is described below; more detail is provided at each link.
<ol>
<li>
Make sure you follow the <a href="dev_intro_philosophy.html">Philosophy
of Zoltan</a> and the <a href="dev_intro_coding.html">Coding Principles
in Zoltan</a>.</li>
<li>
Use the <a href="dev_add_struct.html">Data Structures</a>
provided by Zoltan.</li>
<li>
Implement a <a href="dev_add_lb.html">Load-Balancing Function</a> front-end
to the algorithm. Note that Zoltan load-balance methods should assign objects both to processors and parts, which may be different. The recommended strategy is to assign objects to parts first, then use Zoltan_LB_Part_To_Proc to generate the corresponding processors.</li>
<li>
Add the algorithm to the <a href="dev_add_interface.html">Load-Balancing
Interface Routines</a>.</li>
<li>
Add the <a href="dev_add_params.html">Parameters</a> needed by the algorithm.
Also make sure that the algorithm uses the <a href="../ug_html/ug_param.html#General_Parameters">General Parameters</a> in Zoltan properly, in particular
<a href="../ug_html/ug_alg.html#LB Parameters"><b>Imbalance_Tol</b></a> and
<a href="../ug_html/ug_param.html#Debug Levels in Zoltan"><b>Debug_Level.</b></a></li>
<li>
If necessary, write a routine to free your dynamically allocated data structures.
See tips on <a href="dev_add_memory.html">memory management</a></li>
in Zoltan.</a></li>
<li>
If your algorithm uses persistent data structures,
like the RCB tree with <a href="../ug_html/ug_alg_rcb.html">KEEP_CUTS</a>,
write a routine to copy your load balancing
<a href="dev_add_struct.html#Copy">data structure</a>. </li>
<li>
We recommend you add part remapping to your algorithm using
<a href="dev_add_.html"><b>Zoltan_LB_Remap</b></a>.</li>
<li>
Update the <a href="dev_fortran.html#fortran dev add">Fortran</a>
and <a href="dev_cpp.html">C++</a> interfaces, if necessary.</li>
<li>
Document your new method. The documentation should be written in a format
that can easily be converted into HTML and PDF. Consider adding a
simple application to the <I>examples</I> directory demonstrating the
use of your method.</li>
<li>
Please contact the Zoltan team if you would like your method to be distributed
with future versions of Zoltan.</li>
</ol>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_add_interface.html">Next:&nbsp;
Load-Balancing Interface Routines</a>&nbsp; |&nbsp; <a href="dev_services_debug.html">Previous:&nbsp;
Debugging Services</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

101
thirdParty/Zoltan/docs/dev_html/dev_add_interface.html vendored Normal file
View File

@ -0,0 +1,101 @@
<!-------- @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 Interface Routines</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_add_lb.html">Next</a>&nbsp; |&nbsp; <a href="dev_add.html">Previous</a></i></b></div>
<h2>
<a NAME="new_interface"></a>Load-Balancing Interface Routines</h2>
Any new method that you wish to add to the Zoltan library must have an
interface that conforms to the prototype <b><a href="dev_add_lb.html">LB_FN</a></b>.
Note that the load balancing
function may return either import lists, export lists, or both. All
processes must return the same type of list. If import (export) lists
are not computed, then the variable <i>num_import</i> (<i>num_export</i>)
must be set to a negative number (typically -1) upon return.
Full support of the <a href="../ug_html/ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>
parameter is not required.
If <a href="../ug_html/ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>
is not set to NONE,
the new algorithm may return either import or export lists; the Zoltan
interface will then build the lists requested by
<a href="../ug_html/ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>.
<p>
A new algorithm must be added to the load-balancing interface for use
with parameter
<a href="../ug_html/ug_alg.html#LB_METHOD">LB_METHOD</a>.
An entry for the new algorithm must be added to the enumerated type <b>Zoltan_LB_Method</b>
in <i>lb/lb_const.h</i>. An external <b><a href="dev_add_lb.html">LB_FN</a></b>
prototype for the load-balancing function must also be added to <i>lb/lb_const.h</i>;
see the prototype for function <i>Zoltan_RCB</i> as an example. A character
string describing the new algorithm should be chosen to be used as the parameter
value for
<a href="../ug_html/ug_alg.html#LB_METHOD">LB_METHOD</a>.
In
function <b>Zoltan_LB_Set_LB_Method</b>,
a test for this string should be added
and the <i>Method</i> and <i>LB_Fn</i> fields of the <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
should be set to the new enumerated type value and new load-balancing function
pointer.
<br>&nbsp;
<p>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_add_lb.html">Next:&nbsp;
Load-Balancing Function Implementation</a>&nbsp; |&nbsp; <a href="dev_add.html">Previous:&nbsp;
Adding New Algorithms</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

259
thirdParty/Zoltan/docs/dev_html/dev_add_lb.html vendored Normal file
View File

@ -0,0 +1,259 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 5.6 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: Adding Load-Balancing Functions</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_add_struct.html">Next</a>&nbsp; |&nbsp; <a href="dev_add_interface.html">Previous</a></i></b></div>
<H2>
<A NAME="new_implementation"></A>Load-Balancing Function Implementation</H2>
The new load-balancing algorithm should be implemented as an <B>ZOLTAN_LB_FN</B>.
The type definition for an <B>ZOLTAN_LB_FN</B> is in <I>lb/lb_const.h</I> and
is described below. When the new algorithm is selected,
the <I>LB_Fn</I> field of the <B>Zoltan_Struct</B> is set to point to the <B>ZOLTAN_LB_FN</B>
function for the new algorithm. This pointer is then used in invoking load
balancing in <B><A HREF="../ug_html/ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</A></B>.
<BR>&nbsp;
<P>
<hr>
<HR>typedef int <B>ZOLTAN_LB_FN</B>
(struct&nbsp;<B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>&nbsp;*<I>zz</I>,
float&nbsp;*<I>part_sizes</I>,
int&nbsp;*<I>num_import</I>,
<B><A HREF="dev_lb_types.html">ZOLTAN_ID_PTR</A></B>&nbsp;*<I>import_global_ids</I>,
<B><A HREF="dev_lb_types.html">ZOLTAN_ID_PTR</A></B>&nbsp;*<I>import_local_ids</I>,
int&nbsp;**<I>import_procs</I>,
int&nbsp;**<I>import_to_parts</I>,
int&nbsp;*<I>num_export</I>,
<B><A HREF="dev_lb_types.html">ZOLTAN_ID_PTR</A></B>&nbsp;*<I>export_global_ids</I>,
<B><A HREF="dev_lb_types.html">ZOLTAN_ID_PTR</A></B>&nbsp;*<I>export_local_ids</I>,
int&nbsp;**<I>export_procs</I>,&nbsp;
int&nbsp;**<I>export_to_parts</I>);&nbsp;
<HR>
<BR>The <B>ZOLTAN_LB_FN</B> function type describes the arguments passed to a
load-balancing function. The input to the function is a <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>
containing pointers to application-registered functions to be used in the
load-balancing algorithm. The remaining arguments are output parameters
listing the objects to be imported or exported to the processor in the
new decomposition. The arrays for global and local IDs and source processors
must be allocated by the load-balancing function. The load-balancing function
may return either the import arrays, the export arrays, or both. If no
import data is returned, *<I>num_import </I>must be set to a negative number,
and similarly with *<I>num_export.</I>
Full support of the <a href="../ug_html/ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>
parameter is not required.
If <a href="../ug_html/ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>
is not set to NONE,
the new algorithm may return either import or export lists; the Zoltan
interface will then build the lists requested by
<a href="../ug_html/ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>.
<BR>&nbsp;
<TABLE WIDTH="100%" >
<TR VALIGN=TOP>
<TD VALIGN=TOP WIDTH="20%"><B>Arguments:</B></TD>
<TD WIDTH="80%"></TD>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; zz</I></TD>
<TD>A pointer to the <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>
to be used in the load-balancing algorithm.</TD>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; part_sizes</I></TD>
<TD>Input: an array of part sizes for each weight component.
Entry
<i>part_sizes[i*obj_weight_dim+j]</i>
contains the user-requested
part size for part <i>i</i> with respect to object weight <i>j</i> for
<i>i</i>=0,1,...,number of parts-1, and
<i>j</i>=0,1,...,<i>obj_weight_dim</i>-1.
If the application sets parameter
<i><a href="../ug_html/ug_param.html#OBJ_WEIGHT_DIM">OBJ_WEIGHT_DIM</a></i>,
<i>obj_weight_dim</i> is the set value of
<i><a href="../ug_html/ug_param.html#OBJ_WEIGHT_DIM">OBJ_WEIGHT_DIM</a></i>;
otherwise, <i>obj_weight_dim</i> is one.
</TD>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; num_import</I></TD>
<TD>Upon return, the number of objects to be imported to the processor
for the new decomposition. A negative number indicates that no import data
has been computed and the import arrays should be ignored.</TD>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; import_global_ids</I></TD>
<TD>Upon return, an array of <I>num_import</I> global IDs
of objects to be imported to the processor for the new decomposition.
If this array is non-null, it must be allocated by
<b><a href="dev_add_memory.html#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b>.
</td>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>import_local_ids</I></TD>
<TD>Upon return, an array of <I>num_import</I> local IDs
of objects to be imported to the processor for the new decomposition.
If this array is non-null, it must be allocated by
<b><a href="dev_add_memory.html#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b>.
</td>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>import_procs</I></TD>
<TD>Upon return, an array of size <I>num_import</I> containing the processor
IDs of processors owning (in the old decomposition) the objects to be imported
for the new decomposition.
If this array is non-null, it must be allocated by
<b><a href="dev_add_memory.html#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b>.
</td>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>import_to_parts</I></TD>
<TD>Upon return, an array of size <I>num_import</I> containing the part
IDs of parts to which objects will be imported
<i>in the NEW decomposition</i>.
If this array is non-null, it must be allocated by
<b><a href="dev_add_memory.html#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b>.
</td>
</TR>
<TR VALIGN=TOP>
<TD>&nbsp;&nbsp;&nbsp; <I>num_export</I></TD>
<TD>Upon return, the number of objects to be exported from the processor
for the new decomposition. A negative number indicates that no export data
has been computed and the export arrays should be ignored.</TD>
</TR>
<TR VALIGN=TOP>
<TD>&nbsp;&nbsp;&nbsp; <I>export_global_ids</I></TD>
<TD>Upon return, an array of <I>num_export</I> global IDs
of objects to be exported from the processor for the new decomposition.
If this array is non-null, it must be allocated by
<b><a href="dev_add_memory.html#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b>.
</td>
</TR>
<TR VALIGN=TOP>
<TD>&nbsp;&nbsp;&nbsp; <I>export_local_ids</I></TD>
<TD>Upon return, an array of <I>num_export</I> local IDs
of objects to be exported from the processor for the new decomposition.
If this array is non-null, it must be allocated by
<b><a href="dev_add_memory.html#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b>.
</TD>
</TR>
<TR VALIGN=TOP>
<TD>&nbsp;&nbsp;&nbsp; <I>export_procs</I></TD>
<TD>Upon return, an array of size <I>num_export</I> containing the
processor IDs of processors owning (in the old decomposition) the objects
to be exported for the new decomposition.&nbsp;
If this array is non-null, it must be allocated by
<b><a href="dev_add_memory.html#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b>.
</td>
</TR>
<TR VALIGN=TOP>
<TD>&nbsp;&nbsp;&nbsp; <I>export_to_parts</I></TD>
<TD>Upon return, an array of size <I>num_export</I> containing the
part IDs of parts to which the objects will be
exported for the new decomposition.&nbsp;
If this array is non-null, it must be allocated by
<b><a href="dev_add_memory.html#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b>.
</td>
</TR>
<TR VALIGN=TOP>
<TD></TD>
<TD></TD>
</TR>
<TR VALIGN=TOP>
<TD><B>Returned Value:</B></TD>
<TD></TD>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</TD>
<TD><A HREF="../ug_html/ug_interface.html#Error Codes">Error code</A>.</TD>
</TR>
</TABLE>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_add_struct.html">Next:&nbsp;
Data Structures</A>&nbsp; |&nbsp; <A HREF="dev_add_interface.html">Previous:&nbsp;
Load-Balancing Interface Routines</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

276
thirdParty/Zoltan/docs/dev_html/dev_add_memory.html vendored Normal file
View File

@ -0,0 +1,276 @@
<!-------- @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 Algorithms: How to handle memory</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_add_params.html">Next</a>&nbsp; |&nbsp; <a href="dev_add_struct.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->
<h2>
Memory Management in Zoltan Algorithms</h2>
Zoltan uses a <a href="../ug_html/ug_util_mem.html">memory management
package</a> to simplify debugging of memory problems.
It is strongly recommended that algorithm
developers use the routines in this package, such as
<a href="../ug_html/ug_util_mem.html#Zoltan_Malloc"><b>ZOLTAN_MALLOC</b> </a>,
<a href="../ug_html/ug_util_mem.html#Zoltan_Calloc"><b>ZOLTAN_CALLOC</b> </a> and
<b><a href="../ug_html/ug_util_mem.html#Zoltan_Free">ZOLTAN_FREE</a></b>, instead
of the standard C routines for most memory management.
<p>
Macros that simplify the <a href="dev_lb_types.html#ID alloc">allocation of global and local identifiers (IDs)</a>
are defined in <i>zz/zz_id_const.h</i>. These macros are described in the
<a href="dev_lb_types.html">ID Data Types</a> section. The macros include
error checking for the allocations and, thus, their use is highly recommended.
<p>When a dynamic structure needs to be returned to the application,
special memory allocation routines are needed.&nbsp; For example, the import
and export lists of data to migrate are returned to an application from
<b><a href="../ug_html/ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
and
<b><a href="../ug_html/ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a></b>.
There are two special routines for managing memory for such situations,
called <b><a href="#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b> and <b><a href="#Zoltan_Special_Free">Zoltan_Special_Free</a></b>.
Algorithms must use these functions to maintain compatibility with both
C and Fortran90 applications; these special routines manage memory in a
way that is compatible with both languages.
<p>Some load-balancing algorithms may contain persistent data structures,
that is, data structures that are preserved between calls to the load-balancing
routine. The <a href="dev_lb_structs.html"><b>Zoltan_Struct</b></a> structure contains a field
<a href="dev_add_struct.html"><i>LB.Data_Structure</i></a>
for this purpose, allowing multiple Zoltan structures to preserve
their own decomposition data. The developer should write a function that
frees this data structure.&nbsp; Use <b>Zoltan_RCB_Free_Structure </b>as an
example.
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Special_Malloc"></a>
<hr>
int <b>Zoltan_Special_Malloc</b>(struct
<b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
*<i>zz</i>, void **<i>array</i>, int <i>size</i>, <b>ZOLTAN_SPECIAL_MALLOC_TYPE</b><i>type</i>);&nbsp;
<hr>
<p>The <b>Zoltan_Special_Malloc</b> routine allocates memory to be returned to the application by Zoltan (e.g., the result arrays
of
<b><a href="../ug_html/ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
and
<b><a href="../ug_html/ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a></b>).
Returned memory must be allocated by <b>Zoltan_Special_Malloc</b> to insure it is allocated
by the same language as the application. Memory allocated by <b>Zoltan_Special_Malloc</b>
must be deallocated by <b><a href="#Zoltan_Special_Free">Zoltan_Special_Free</a></b>.
<br>&nbsp;
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; zz</i></td>
<td>The Zoltan structure currently in use.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; array</i></td>
<td>
Upon return, a pointer to the allocated space.
Usually of type int** or <b><a href="dev_lb_types.html">ZOLTAN_ID_PTR</a></b>*.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; size</i></td>
<td>The number of elements (not bytes) to be allocated.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>type</i></td>
<td>The type of array to allocate. Must be one of <b>ZOLTAN_SPECIAL_MALLOC_INT</b>,
<b>ZOLTAN_SPECIAL_MALLOC_GID</b>
or <b>ZOLTAN_SPECIAL_MALLOC_LID</b> for processor numbers, <a href="dev_lb_types.html">global IDs</a> and <a href="dev_lb_types.html">local IDs</a>, respectively.
</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>
<td>1 if the allocation succeeded; 0 if it failed.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Example:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>
<tt>
ierr = <b>Zoltan_Special_Malloc</b>(<i>zz</i>, (void **)<i>import_gid</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <i>num_import</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>ZOLTAN_SPECIAL_MALLOC_GID</b>);
</tt>
</td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>Allocates an array with <i>num_import</i> <a href="dev_lb_types.html">global IDs</a>
and returns a pointer to the allocated space in <i>import_gid</i>.
</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Special_Free"></a>
<hr>
int <b>Zoltan_Special_Free</b>(struct <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
*<i>zz</i>, void **<i>array</i>,<b> ZOLTAN_SPECIAL_MALLOC_TYPE</b> <i>type</i>);&nbsp;
<hr>
<p><b>Zoltan_Special_Free</b> frees memory allocated by <b><a href="#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b>.
The array pointer is set to NULL upon return.
<br>&nbsp;
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; zz</i></td>
<td>The Zoltan structure currently in use.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; array</i></td>
<td>The array to be freed. Upon return, the pointer is set to NULL.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>type</i></td>
<td>The type of the array. Must be one of <b>ZOLTAN_SPECIAL_MALLOC_INT</b>,
<b>ZOLTAN_SPECIAL_MALLOC_GID</b>
or <b>ZOLTAN_SPECIAL_MALLOC_LID</b> for processor numbers, <a href="dev_lb_types.html">global IDs</a> and <a href="dev_lb_types.html">local IDs</a>, respectively.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>
<td>1 if the deallocation succeeded; 0 if it failed.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Example:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>
<tt>
ierr = <b>Zoltan_Special_Free</b>(<i>zz</i>, (void **)<i>import_gid</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>ZOLTAN_SPECIAL_MALLOC_GID</b>);
</tt>
</td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>Frees the <b><a href="dev_lb_types.html">global IDs</a></b>
array <i>import_gid</i> and sets it to NULL.</td>
</tr>
</table>
<br>&nbsp;
<p>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_add_params.html">Next:&nbsp;
Parameters</a>&nbsp; |&nbsp; <a href="dev_add_struct.html">Previous:&nbsp;
Data Structures</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

118
thirdParty/Zoltan/docs/dev_html/dev_add_params.html vendored Normal file
View File

@ -0,0 +1,118 @@
<!-------- @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 Parameters</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_add_remap.html">Next</a>&nbsp; |&nbsp; <a href="dev_add_memory.html">Previous</a></i></b></div>
<h2>
<a NAME="new_parameters"></a>Adding new parameters</h2>
All parameters in Zoltan should be set and accessed through the <a href="dev_services_params.html">parameter
setting routines</a>. To add a new parameter to an existing method, you
need to do the following:
<ul>
<li>
In the source code for the desired method, search for&nbsp; the place where
the static array of parameters is defined. It will look something like:
<i>static
PARAM_VARS Method_params[] = { ... }</i>.&nbsp; Add a line with the name
of the new parameter, a pointer to the variable you want to associate (usually
NULL), and its type.</li>
<li>
In the method source code, bind the parameter to a local variable through
<b><a href="dev_services_params.html#Zoltan_Bind_Param">Zoltan_Bind_Param</a></b>.
Make sure you do this before <b><a href="dev_services_params.html#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals
</a></b>is
invoked.</li>
<li>
Update the parameter function for the method in question. This routine
is typically called <b>Zoltan_</b><i>Method</i><b>_Set_Param</b><i>. </i>This
routine checks if a given string is a valid parameter for that method.
It may also verify the values.</li>
</ul>
When you add a new method to Zoltan, you also need to:
<ul>
<li>
Write a parameter function for your method that checks whether a given
string and value is a valid parameter pair for your method. See <b>Zoltan_RCB_Set_Param</b>
in <i>rcb/rcb.c</i> for an example.</li>
<li>
Let your method access the parameters via <b><a href="dev_services_params.html#Zoltan_Bind_Param">Zoltan_Bind_Param
</a></b>and
<b><a href="dev_services_params.html#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>.</li>
<li>
Change the parameter function array in <i>params/set_params.c</i> to include
your parameter function. Simply add a new entry to the static array that
looks like: <i>static ZOLTAN_SET_PARAM_FN * Param_func[] = {...}</i>.</li>
<li>
Make sure your method uses the <a href="../ug_html/ug_param.html#General_Parameters">key
parameters</a> in Zoltan correctly.</li>
</ul>
One useful convention is to put your method routine and your corresponding
parameter function in the same source file. This way you can define the
parameters in a static array. This convention eliminates&nbsp; the risk
of bugs caused by duplicate declarations (that are, incorrectly, not identical).
<br>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_add_remap.html">Next:&nbsp;
Part Remapping</a>&nbsp; |&nbsp; <a href="dev_add_memory.html">Previous:&nbsp;
Memory Management</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

248
thirdParty/Zoltan/docs/dev_html/dev_add_remap.html vendored Normal file
View File

@ -0,0 +1,248 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 5.6 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: Part Remapping</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_mig.html">Next</a>&nbsp; |&nbsp; <a href="dev_add_params.html">Previous</a></i></b></div>
<H2>
<A NAME="new_implementation"></A>Part Remapping</H2>
Part remapping can be incorporated into load-balancing algorithms.
The part remapping algorithm works as follows:
<ul>
<li>
After partitioning within an <a href="dev_add_lb.html"><b>ZOLTAN_LB_FN</b></a>
but before import or export lists are built, the partitioning algorithm calls
<a href="#Zoltan_LB_Remap"><b>Zoltan_LB_Remap</b></a>.
</li>
<li>
<a href="#Zoltan_LB_Remap"><b>Zoltan_LB_Remap</b></a> builds a bipartite
graph based on local import or export information (depending on which is
available in the partitioning algorithm). Vertices of the graph are
processor or part numbers used in the old (input to the partitioner)
and new (computed by the partitioner) decompositions. Edges connect
old and new vertices; edge weight for edge <i>e<sub>ij</sub></i> is the
number of objects in old part <i>i</i> that are also in new part
<i>j</i>. The bipartite graph is stored as a hypergraph, so that Zoltan's
hypergraph matching routines may be applied.
</li>
<li>
<a href="#Zoltan_LB_Remap"><b>Zoltan_LB_Remap</b></a> gathers the local
hypergraph edges onto each processor and performs a serial matching of
the vertices. This matching defines the remapping.
</li>
<li>
<a href="#Zoltan_LB_Remap"><b>Zoltan_LB_Remap</b></a> remaps the input
processor and part information to reflect the remapping and returns
the result to the application. It also builds array <i>zz->LB.Remap</i>
that is used in other functions (e.g.,
<b><a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Box_PP_Assign">Zoltan_LB_Box_PP_Assign</a></b> and
<b><a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Point_PP_Assign">Zoltan_LB_Point_PP_Assign</a></b>).
</li>
<li>
Using the remapping information returned from
<a href="#Zoltan_LB_Remap"><b>Zoltan_LB_Remap</b></a>, the partitioning
algorithm builds the import or export lists to return to the application.
Note: if the partitioning algorithm builds import lists, data may have to be
moved to appropriate processors before building import lists to reflect
the remapping; see <i>rcb/shared.c</i> for an example.
</li>
</ul>
<P>
<hr><a NAME="Zoltan_LB_Remap"></a>
<HR>int <B>Zoltan_LB_Remap</B>
(struct&nbsp;<B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>&nbsp;*<I>zz</I>,
int&nbsp;*<I>new_map</I>,
int&nbsp;<I>num_obj</I>,
int&nbsp;*<I>procs</I>,
int&nbsp;*<I>old_parts</I>,
int&nbsp;*<I>new_parts</I>,
int&nbsp;<I>export_list_flag</I>);
<HR>
<BR>
<b>Zoltan_LB_Remap</b> remaps computed part (or processor) numbers in
an attempt to maximize the amount of data that does not have to be migrated
to the new decomposition. It is incorporated directly into partitioning
algorithms, and should be called after the new decomposition is computed
but before return lists (import or export lists) are created.
<b>Zoltan_LB_Remap</b> should be invoked when Zoltan parameter
<i><a href="../ug_html/ug_alg.html#REMAP">REMAP</a></i> is one.
Even when
<i><a href="../ug_html/ug_alg.html#REMAP">REMAP</a></i> is one,
remapping is not done under a number of conditions; these conditions are
listed with the description of
<i><a href="../ug_html/ug_alg.html#REMAP">REMAP</a></i>.
<BR>&nbsp;
<TABLE WIDTH="100%" >
<TR VALIGN=TOP>
<TD VALIGN=TOP WIDTH="20%"><B>Arguments:</B></TD>
<TD WIDTH="80%"></TD>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; zz</I></TD>
<TD>A pointer to the <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>
used in the partitioning algorithm.</TD>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; new_map</I></TD>
<TD>Upon return, a flag indicating whether remapping was actually done.
Remapping is not done under a number of conditions (described with
parameter
<i><a href="../ug_html/ug_alg.html#REMAP">REMAP</a></i>) or when the
computed remap gives a worse or equivalent result than the decomposition
computed by the partitioning algorithm.
</TD>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; num_obj</I></TD>
<TD>Input: the number of objects the processor knows about after
computing the decomposition. If the partitioning algorithm computes
export lists, <i>num_obj</i> is the number of objects stored on the
processor; if it computes import lists, <i>num_obj</i> is the number of
objects that will be stored on the processor in the new decomposition.
</td>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; procs</I></TD>
<TD>
Upon input:
an array of size <i>num_obj</i> containing processor
assignments for the objects;
if <i>export_list_flag</i> == 1,
<i>procs</i> contains processor assignments
in the NEW decomposition (computed by the partitioner); otherwise,
<i>procs</i> contains processor assignments
in the OLD decomposition (input by the application).
Upon return, <i>procs</i> contains remapped
processor assignments for the NEW decomposition, regardless of the value of
<i>export_list_flag</i>.
</td>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>old_parts</I></TD>
<TD>
Upon input:
an array of size <i>num_obj</i> containing part
assignments for the objects in the OLD decomposition (input by the
application).
</td>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>new_parts</I></TD>
<TD>
Upon input:
an array of size <i>num_obj</i> containing part
assignments for the objects in the NEW decomposition (computed by the
partitioning algorithm).
Upon return:
<i>new_parts</i> contains remapped part assignments in the NEW decomposition.
</td>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>export_list_flag</I></TD>
<TD>
Flag indicating whether the partitioning algorithm computes
export lists or import lists. The procedure
for building the bipartite
graph depends on whether
the partitioning algorithm knows export or import information.
</td>
</TR>
<TR VALIGN=TOP>
<TD></TD>
<TD></TD>
</TR>
<TR VALIGN=TOP>
<TD><B>Returned Value:</B></TD>
<TD></TD>
</TR>
<TR VALIGN=TOP>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</TD>
<TD><A HREF="../ug_html/ug_interface.html#Error Codes">Error code</A>.</TD>
</TR>
</TABLE>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_mig.html">Next:&nbsp;
Migration Tools</A>&nbsp; |&nbsp; <A HREF="dev_add_params.html">Previous:&nbsp;
Adding new parameters</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

228
thirdParty/Zoltan/docs/dev_html/dev_add_struct.html vendored Normal file
View File

@ -0,0 +1,228 @@
<!-------- @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>&nbsp;
|&nbsp; <a href="dev_add_memory.html">Next</a>&nbsp; |&nbsp; <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).&nbsp;
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>&nbsp;* If the previous data structure still exists, free the Dots
first;
<br>&nbsp;* the other fields can be reused.
<br>&nbsp;*/
<br>if (zz->LB.Data_Structure == NULL) {
<br>&nbsp;&nbsp; rcb = (RCB_STRUCT *) <a href="../ug_html/ug_util_mem.html#Zoltan_Malloc">ZOLTAN_MALLOC</a>(sizeof(RCB_STRUCT));
<br>&nbsp;&nbsp; zz->LB.Data_Structure = (void *) rcb;
<br>&nbsp;&nbsp; rcb->Tree_Ptr = (struct rcb_tree *)&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="../ug_html/ug_util_mem.html#Zoltan_Malloc">ZOLTAN_MALLOC</a>(zz->Num_Proc*sizeof(struct
rcb_tree));
<br>&nbsp;&nbsp; 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>&nbsp;&nbsp; rcb = (RCB_STRUCT *) zz->LB.Data_Structure;
<br>&nbsp;&nbsp; <a href="../ug_html/ug_util_mem.html#Zoltan_Free">ZOLTAN_FREE</a>(&amp;(rcb->Dots));
<br>}
</tt>
</td>
</tr>
<caption ALIGN=BOTTOM><i>Example demonstrating allocation of data structures
for the RCB algorithm.&nbsp; (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.&nbsp;
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.&nbsp;
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>.&nbsp; 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>&nbsp;
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr>
<td><a NAME="query_example"></a>&nbsp;&nbsp;
<tt>
<br>/*
<br>&nbsp;* Allocate space for objects.&nbsp; Allow extra space
<br>&nbsp;* for objects that are imported to the processor.
<br>&nbsp;*/
<p>*num_obj = zz->Get_Num_Obj(zz->Get_Num_Obj_Data, &amp;ierr);
<br>if (ierr) {
<br>&nbsp; <a href="dev_intro_coding.html#ZOLTAN_PRINT">ZOLTAN_PRINT_ERROR</a>(zz->Proc,
yo,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"Error returned from Get_Num_Obj.");
<br>&nbsp; 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&nbsp; = <a href="dev_lb_types.html#ID alloc">ZOLTAN_MALLOC_LID_ARRAY</a>(zz, (*max_obj));
<br>*dots = (struct Dot_Struct *)
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <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 &amp;&amp; !(*local_ids)) ||
!(*dots)) {
<br>&nbsp; <a href="dev_intro_coding.html#ZOLTAN_PRINT">ZOLTAN_PRINT_ERROR</a>(zz->Proc,
yo, "Insufficient memory.");
<br>&nbsp; return(<a href="../ug_html/ug_interface.html#Error Codes">ZOLTAN_MEMERR</a>);
<br>}
<p>if (*num_obj > 0) {
<p>&nbsp; if (wgtflag) {
<p>&nbsp;&nbsp;&nbsp; /*
<br>&nbsp;&nbsp;&nbsp;&nbsp; *&nbsp; Allocate space for object weights.
<br>&nbsp;&nbsp;&nbsp;&nbsp; */
<p>&nbsp;&nbsp;&nbsp; objs_wgt = (float *) <a href="../ug_html/ug_util_mem.html#Zoltan_Malloc">ZOLTAN_MALLOC</a>((*num_obj)*sizeof(float));
<br>&nbsp;&nbsp;&nbsp; if (!objs_wgt) {
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="dev_intro_coding.html#ZOLTAN_PRINT">ZOLTAN_PRINT_ERROR</a>(zz->Proc,
yo, "Insufficient memory.");
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return(<a href="../ug_html/ug_interface.html#Error Codes">ZOLTAN_MEMERR</a>);
<br>&nbsp;&nbsp;&nbsp; }
<br>&nbsp;&nbsp;&nbsp; for (i = 0; i &lt; *num_obj; i++) objs_wgt[i]
= 0.;
<br>&nbsp; }
<p>&nbsp; /*
<br>&nbsp;&nbsp; *&nbsp; Get list of objects' IDs and weights.
<br>&nbsp;&nbsp; */
<p>&nbsp; <a href="dev_services_objlist.html">Zoltan_Get_Obj_List</a>(zz, *global_ids, *local_ids, wgtflag,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; objs_wgt, &amp;ierr);
<br>&nbsp; if (ierr) {
<br>&nbsp;&nbsp;&nbsp; <a href="dev_intro_coding.html#ZOLTAN_PRINT">ZOLTAN_PRINT_ERROR</a>(zz->Proc,
yo,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"Error returned from Zoltan_Get_Obj_List.");
<br>&nbsp;&nbsp;&nbsp; <a href="../ug_html/ug_util_mem.html#Zoltan_Free">ZOLTAN_FREE</a>(&amp;objs_wgt);
<br>&nbsp;&nbsp;&nbsp; return(ierr);
<br>&nbsp; }
<p>&nbsp; ierr = initialize_dot(zz, *global_ids, *local_ids, *dots,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
*num_obj, wgtflag, objs_wgt);
<br>&nbsp; if (ierr == ZOLTAN_FATAL || ierr == ZOLTAN_MEMERR) {
<br>&nbsp;&nbsp;&nbsp; <a href="dev_intro_coding.html#ZOLTAN_PRINT">ZOLTAN_PRINT_ERROR</a>(zz->Proc,
yo,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"Error returned from initialize_dot.");
<br>&nbsp;&nbsp;&nbsp; <a href="../ug_html/ug_util_mem.html#Zoltan_Free">ZOLTAN_FREE</a>(&amp;objs_wgt);
<br>&nbsp;&nbsp;&nbsp; return(ierr);
<br>&nbsp; }
<p>&nbsp; <a href="../ug_html/ug_util_mem.html#Zoltan_Free">ZOLTAN_FREE</a>(&amp;objs_wgt);
<br>}
</tt>
</td>
</tr>
<caption ALIGN=BOTTOM><i>Example demonstrating how data structures are
built for the RCB algorithm.&nbsp; (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>&nbsp; |&nbsp; <a href="dev_add_memory.html">Next:&nbsp;
Memory Management</a>&nbsp; |&nbsp; <a href="dev_add_lb.html">Previous:&nbsp;
Load-Balancing Function Implementation</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
<br>&nbsp;
</body>
</html>

227
thirdParty/Zoltan/docs/dev_html/dev_cpp.html vendored Normal file
View File

@ -0,0 +1,227 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="lee ann fisk, lafisk@sandia.gov">
<TITLE> Zoltan Developer's Guide: C++ Interface</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_refs.html">Next</a>&nbsp; |&nbsp; <a href="dev_fortran.html">Previous</a></i></b></div>
<H2>
<A NAME="cpp dev"></A>C++ Interface</H2>
As with the Fortran interface just described, any change to the user
API of Zoltan should be reflected in the C++ interface. This section
explains the conventions used in the C++ interface, which you will want
to follow when you modify or expand it.
<UL><A HREF="#cpp dev classes">Classes</A><BR>
<A HREF="#cpp dev conventions">Programming Conventions</A>
<UL>
<A HREF="#cpp dev namespaces"><I>Namespaces</I></A><BR>
<A HREF="#cpp dev cnames"><I>Class names</I></A><BR>
<A HREF="#cpp dev mnames"><I>Method names</I></A><BR>
<A HREF="#cpp dev constmethods"><I>Const methods</I></A><BR>
<A HREF="#cpp dev parameters"><I>Declaration of method parameters</I></A><BR>
<A HREF="#cpp dev copy"><I>Copy constructor, copy operator</I></A>
</UL>
<A HREF="#cpp dev updating">Keeping the C++ interface up-to-date</A><BR>
</UL>
<H3> <A NAME="cpp dev classes"></A>Classes</H3>
The C language Zoltan library already observes the principles of
object oriented program design. Each sub function of Zoltan (load
balancing, timing, etc.) has a data structure
associated with it. This data structure maintains all the state required
for one instance of that sub function. Each request of the library for
some operation requires that data structure.
<P>The classes in the Zoltan C++ library follow the structure just described.
Each class is defined in a header
file and encapsulates a Zoltan data structure and the functions that
operate on that structure. A C++ application wishing to use a
feature of Zoltan, would include the feature's header file in it's source, and
link with the Zoltan C library.
<P>The C language load balancing data stucture
(<B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>)
and the C functions that operate on it are accessed
through the C++ <B>Zoltan</B> class, defined in <I>zoltan_cpp.h</I>.
<P>The communication package is encapsulated the <B>Zoltan_Comm</B> class
defined in <I>zoltan_comm_cpp.h</I>.
Again, to use the communication utility of Zoltan from a C++ program,
include <I>zoltan_comm_cpp.h</I> and use the C++ methods defined there.
<P>The C++ Zoltan timer class is called <B>Zoltan_Timer_Object</B> and
is defined in <I>zoltan_timer_cpp.h</I>.
<P>The distributed directory utility of Zoltan is encapsulated in the
class <B>Zoltan_DD</B> defined in <I>zoltan_dd_cpp.h</I>
<H3> <A NAME="cpp dev conventions"></A>Programming Conventions</H3>
When modifying the interface to Zoltan , you will want to modify
the appropriate C++ header file accordingly. This section describes the
conventions to follow to maintain a consistent and correct library interface
for the C++ user of Zoltan.
<H4><I><A NAME="cpp dev namespaces">Namespaces</A></I></H4>
In order to maintain portability across platforms, there is no Zoltan
namespace. Many C++ compilers do not support namespaces at this time.
The name of each Zoltan class begins with <B>Zoltan_</B>, and hopefully
this will never clash with another namespace.
<H4><I><A NAME="cpp dev cnames">Class names</A></I></H4>
Class names are <B>Zoltan_</B> followed by text indicating the sub
function of Zoltan that is encapsulated by the class.
<H4><I><A NAME="cpp dev mnames">Method names</A></I></H4>
Method names are derived from the C library function names in such a
way that the name will be obvious to a person familiar with the C library.
We remove the beginning of the C library name, the part that identifies
the subset of the Zoltan library that the function is part of, and keep
the last part of the C library name, the part that describes what the
function does. For example the C function <B>Zoltan_LB_Partition</B> becomes
the C++ method <B>LB_Partition</B> in the class <B>Zoltan</B> and
C function <B>Zoltan_Comm_Create</B> becomes the C++ method
<B>Create</B> in the class <B>Zoltan_Comm</B>.
<H4><I><A NAME="cpp dev constmethods">Const methods</A></I></H4>
All class methods which can be declared <B>const</B>, because they
do not modify the object, should be declared <B>const</B>. This allows
C++ programmers to call these methods on their <B>const</B> objects.
<H4><I><A NAME="cpp dev parameters">Declaration of method parameters</A></I></H4>
Parameters that are not changed in the method should be declared <B>const</B>.
This can get complicated, but it helps to read declarations from right to
left. <B>const int * & p</B> says <I>p is a reference to a pointer to
a const int</I> and means the method will not change the value pointed
to by <I>p</I>. On the other hand <B>int * const & p</B> says that
<I>p is a reference to a const pointer to int</I> so the method will
not change the pointer.
<P>Variables that are passed by value in a C function will be passed by
const reference in the C++ method. This is semantically the same, but
it is more efficient, and it will work with temporary variables created
by a compiler.
<P>If a C function takes a pointer to a single built-in type (not an aggregate
type), the associated C++ method will take a reference variable.
If a C function takes a pointer to a pointer, the C++ function will take
a pointer reference. The references are more efficient, and it is
the behavior a C++ programmer expects.
A pointer to an array remains a pointer to an array.
<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
<TR> <TH>C function parameter</TH> <TH>C++ method parameter</TH> <TH> method's const behavior</TR>
<TR> <TD>int val</TD>
<TD>const int &val</TD>
<TD>won't change value</TD></TR>
<TR> <TD>int *singlep</TD>
<TD>int &singlep <br> const int &singlep</TD>
<TD>may change value <br> won't change value</TD></TR>
<TR> <TD>int **singlep</TD>
<TD>int *&singlep <br> const int * &p <br> int *const &p <br> const int * const &p</TD>
<TD>may change pointer or value<br>won't change value<br>won't change pointer to value<br>won't change anything</TD></TR>
<TR> <TD>int *arrayp</TD>
<TD>int *arrayp <br> const int * arrayp</TD>
<TD>may change array contents <br> won't change array contents</TD> </TR>
</TABLE>
<P>If a C function takes a pointer to an array of <I>char</I>, the
associated C++ method will take a <I>string</I> object.
<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
<TR> <TH>C function parameter</TH> <TH>C++ method parameter</TH> </TR>
<TR> <TD>char *fname</TD> <TD>std::string &fname</TD> </TR>
</TABLE>
<P> In all honesty, it is tedious to carefully apply const'ness in
parameter declarations, and we did not do it consistently throughout the
C++ wrapping of Zoltan. Please feel free to add <I>const</I> declarations
where they belong, and try to use them correctly if you add or modify Zoltan
C++ methods.
<H4><I><A NAME="cpp dev copy">Copy constructor, copy operator</A></I></H4>
Each class should have a copy constructor and a copy operator.
<H3> <A NAME="cpp dev updating"></A>Keeping the C++ interface up-to-date</H3>
Here we provide a checklist of things to be done when the C interface to
the Zoltan library is changed:
<UL>
<LI>If a new major component is added to Zoltan, create a C++ class for
that component in a new header file, using the programming conventions
described above. </LI>
<LI>If functions are added or removed, or their parameter lists are
changed, then update the header file defining the class that contains
those functions.</LI>
<LI>When Zoltan data structures are changed, be sure to change the C functions
that copy the data structure. (They contain <B>Copy</B> in their name.)
Correct copying is more important in C++,
where the compiler may generate new temporary objects, than it is in C.</LI>
<LI>If you change the C++ API, be sure to change:
<UL>
<LI><B>zCPPdrive</B>, the test program for the Zoltan C++ library</LI>
<LI>the C++ examples in the <B>Examples</B> directory</LI>
<LI>the method prototypes in the <A HREF="../ug_html/ug.html">Zoltan User's Guide</A>.</LI>
</UL>
</UL>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_refs.html">Next:&nbsp;
References</A>&nbsp; |&nbsp; <A HREF="dev_fortran.html">Previous:&nbsp;
FORTRAN Interface</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

172
thirdParty/Zoltan/docs/dev_html/dev_degenerate.html vendored Normal file
View File

@ -0,0 +1,172 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 5.6 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="lee ann fisk, lafisk@sandia.gov">
<TITLE> Zoltan Developer's Guide: Degenerate Geometries</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_hsfc.html">Previous</a></i></b></div>
<H2>
<A NAME="HSFC"></A>Appendix: Handling Degenerate Geometries</H2>
The geometry processed by one of the geometric methods
<a href="dev_rcb.html">RCB</a>, <a href="dev_rib.html">RIB</a>, or
<a href="dev_hsfc.html">HSFC</a>
may be degenerate. By this we mean
it may have 3-dimensional coordinates but be essentially flat, or
it may have 3 or 2-dimensional coordinates but be essentially a line
in space. If we treat the geometry as a lower dimensional object
for the purpose of partitioning, the result may be a more natural
partition (one the user would have expected) and a faster
run time.
<p>
The caller may set the <B>REDUCE_DIMENSIONS</B> parameter to TRUE
in any of the three geometric methods if they want Zoltan to check
for a degenerate condition and do lower dimensional partitioning
if such a condition if found. They may set the <B>DEGENERATE_RATIO</B>
to specify how flat or thin a geometry must be to be considered
degenerate.
<p>
<H3>
Outline of Algorithm</H3>
All three geometric methods call
<a href="dev_services_objlist.html#Zoltan_Get_Coordinates"><b>Zoltan_Get_Coordinates</b></a>
to obtain the
problem coordinates. If <B>REDUCE_DIMENSIONS</B> is TRUE, we check
in this function to see if the geometry is degenerate. If it is,
we transform the coordinates to the lower dimensional space, flag
that the problem is now lower dimensional, and return the transformed
coordinates. The
<a href="dev_rcb.html">RCB</a>, <a href="dev_rib.html">RIB</a>, or
<a href="dev_hsfc.html">HSFC</a>
calculation is performed on the new coordinates in the lower dimensional
space.
<p>
If <B>KEEP_CUTS</B> is TRUE, the transformation is saved so that in
<a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Box_Assign"><b>Zoltan_LB_Box_Assign</b></a> or <a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Point_Assign"><b>Zoltan_LB_Point_Assign</b></a>
the coordinates can be transformed before the assignment is calculated.
If <B>RCB_REUSE</B> is TRUE in the <a href="dev_rcb.html">RCB</a> method,
the transformation is also saved. On re-partitioning, we can do some
simple tests to see if the degeneracy condition has changed before
completely re-calculating the coordinate transformation.
<p>
To determine if the geometry is degenerate, we calculate
the same inertial matrix that is calculated for <a href="dev_rib.html">RIB</a>,
except that we ignore vertex weights. The 3 orthogonal eigenvectors
of the inertial matrix describe the three primary directions of the
geometry. The bounding box oriented in these directions is tested
for degeneracy. In particular (for a 3 dimensional geometry) if the
length of the longest side divided by the length of the shortest side
exceeds the DEGENERATE_RATIO, we consider the geometry to be flat. If
in addition, the length longest side divided by the length of the
middle side exceeds the
DEGENERATE_RATIO, we consider the geometry to be essentially a line.
<p>
If a 3 dimensional geometry is determined to be flat, we transform
coordinates to a coordinate system where the XY plane corresponds
to the oriented bounding box,
and project all coordinates to that plane. These
X,Y coordinates are returned to the partitioning algorithm, which
performs two dimensional partitioning. Similarly if the geometry
is very thin, we transform coordinates to a coordinate system
with the X axis going through the
bounding box in it's principal direction, and project all points to
that axis. Then one dimensional partitioning is performed.
<p>
There is a small problem in calculating
<a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Box_Assign"><b>Zoltan_LB_Box_Assign</b></a>
when the partitioning was performed
on transformed geometry. The caller provides the box vertices in
problem coordinates, but the partition was calculated in
transformed coordinates. When the vertices are transformed, they
are in general no longer the vertices of an axis-aligned box in
the new coordinate system. The
<B>Box_Assign</B> calculation requires an axis-aligned box, and
so we use the bounding box of the transformed vertices. The resulting
list of processes or parts intersecting the box may therefore
contain some processes or parts which actually do not intersect
the box in problem coordinates, however it will not omit any.
<H3>Data Structure Definitions</H3>
The transformation is stored in a <B>Zoltan_Transform_Struct</B>
structure which is
defined in <i>zz/zz_const.h</i>. It is saved as part of the algorithm
specific information stored in the
<b><a href="dev_add_struct.html">LB.Data_Structure</a></b> field of the
<b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>.
The flag that indicates whether the geometry was found to be
degenerate is the <B>Target_Dim</B> field of this structure.
<p>
To use the degenerate geometry detection capability from a new
geometric method, you would add a <B>Zoltan_Transform_Struct</b>
structure to the algorithm specific data structure, add code to
<B>Zoltan_Get_Coordinates</B> to look for it, and check the
<B>Target_Dim</B> field on return to see if the problem dimension
was reduced. You would also need to include the
coordinate transformation in your Box_Assign and Point_Assign
functionality.
<BR>&nbsp;
<BR>&nbsp;
<P>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp;
|&nbsp; <A HREF="dev_hsfc.html"> Previous:&nbsp; Hibert Space Filling Curve (HSFC)</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

74
thirdParty/Zoltan/docs/dev_html/dev_dist.html vendored Normal file
View File

@ -0,0 +1,74 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: Distribution</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_dist_cvs.html">Next</a>&nbsp; |&nbsp; <a href="dev_intro_sqe.html">Previous</a></i></b></div>
<H2>
<A NAME="distribution"></A>Zoltan Distribution</H2>
The organization of the Zoltan software distribution is described in the
following sections.&nbsp; Full pathnames are specific to Sandia's CSRI SON
LAN.
<BLOCKQUOTE><A HREF="dev_dist_cvs.html">CVS (source code control)</A>
<BR><A HREF="dev_dist_dir.html">Layout of Directories</A>
<BR><A HREF="dev_dist_compile.html">Compilation and Makefiles</A></BLOCKQUOTE>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_dist_cvs.html">Next:&nbsp;
CVS</A>&nbsp; |&nbsp; <A HREF="dev_intro_sqe.html">Previous:&nbsp; Zoltan
Quality Assurance</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

124
thirdParty/Zoltan/docs/dev_html/dev_dist_compile.html vendored Normal file
View File

@ -0,0 +1,124 @@
<!-------- @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: Compilation</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_lb.html">Next</a>&nbsp; |&nbsp; <a href="dev_dist_dir.html">Previous</a></i></b></div>
<h2>
<a NAME="compilation"></a>Compilation and Makefiles</h2>
The Zoltan distribution includes a main (top-level) makefile with targets
for the Zoltan library, the test driver programs, and some graphical tools.
When the library is
<a href="../ug_html/ug_usage.html#Building the Library">compiled for a specific target platform</a>, <i>A</i>, Autotools and CMake obtain provide
platform-specific configuration information.
<p>
Both the Autotools and CMake build systems must be maintained in Zoltan.
Thus, new source code files and directories must be added for both systems.
It is easiest to follow the examples of existing files in the build
environments; good examples
are <i>hsfc.h</i>, <i>hsfc.c</i>, <i>dr_loadbal_const.h</i> and
<i>dr_loadbal.c</i>.
<p>
To add new source files or source directories:
<ul>
<li>
Autotools: Add new library files or directories to
<i>zoltan/src/Makefile.am</i>; add
new driver files to <i>zoltan/src/driver/Makefile.am</i>.
In the main
zoltan directory, run the <i>bootstrap-local</i> script to rebuild the
automated Makefiles.
</li>
<li>
CMake: Add new library files to <i>zoltan/src/CMakeLists.txt</i>; add
new driver files to <i>zoltan/src/driver/CMakeLists.txt</i>.
</li>
</ul>
<p>
Alternatively, new algorithms can be added as separate libraries with which
Zoltan may link.
The implementation of the <a href="../ug_html/ug_alg_parmetis.html">ParMETIS</a>
interface in Zoltan can serve as an example.
<p>
To add new third-party libraries:
<ul>
<li>
Autotools: Add checks new library paths and include files to
<i>zoltan/configure.ac</i>. Search for the string "parmetis" in
<i>zoltan/configure.ac</i>, and follow
its example for the new library.
Also edit
<i>zoltan/src/include/Zoltan_config.h.in</i> to include a macro for
the new third-party library; follow the example of "HAVE_PARMETIS".
In the main
zoltan directory, run the <i>bootstrap-local</i> script to rebuild the
automated configure and Makefiles.
</li>
<li>
CMake:
Follow the instructions in <i>Trilinos/cmake/HOWTO.ADD_TPL</i>
In <i>zoltan/src/CMakeLists.txt</i>
and <i>zoltan/cmake/Zoltan_config.h.in</i>,
follow the example of "HAVE_PARMETIS".
</li>
</ul>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_lb.html">Next:&nbsp;
Zoltan Interface and Data Structures</a>&nbsp; |&nbsp; <a href="dev_dist_dir.html">Previous:&nbsp;
Layout of Directories</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

95
thirdParty/Zoltan/docs/dev_html/dev_dist_cvs.html vendored Normal file
View File

@ -0,0 +1,95 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: CVS</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_dist_dir.html">Next</a>&nbsp; |&nbsp; <a href="dev_dist.html">Previous</a></i></b></div>
<H2>
<A NAME="CVS"></A>CVS</H2>
The source code and documentation for the Zoltan library is maintained
under the Concurrent Versions System (CVS) software. CVS allows multiple
developers to edit their own copies of the software and merges updated
versions with the developers' own versions. Zoltan's repository
is part of the <a href="https://trilinos.sandia.gov">Trilinos</a> repository.
Developers must set the CVSROOT environment variable to the repository
directory:
<BLOCKQUOTE>setenv CVSROOT <i>username</i>@software.sandia.gov:/space/CVS
</BLOCKQUOTE>
where <i>username</i> is the developer's username on the CVS server
software.sandia.gov.
Since Zoltan is part of Trilinos, it is best to check out Trilinos from
the repository:
<BLOCKQUOTE>cvs checkout -P Trilinos</BLOCKQUOTE>
Zoltan is then in directory Trilinos/packages/zoltan.
<p>
Alternatively, one can get a working copy of only the Zoltan software:
<BLOCKQUOTE>cvs checkout -P zoltan</BLOCKQUOTE>
However, changes to the
<a href="../ug_html/ug_usage.html#TrilinosAutotools">Autotools build
environment</a> require directories above the Zoltan directory in
the Trilinos repository, so it is best to check out the entire Trilinos
repository.
<P>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_dist_dir.html">Next:&nbsp;
Layout of Directories</A>&nbsp; |&nbsp; <A HREF="dev_dist.html">Previous:&nbsp;
Zoltan Distribution</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

280
thirdParty/Zoltan/docs/dev_html/dev_dist_dir.html vendored Normal file
View File

@ -0,0 +1,280 @@
<!-------- @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: Directory Layout</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_dist_compile.html">Next</a>&nbsp; |&nbsp; <a href="dev_dist_cvs.html">Previous</a></i></b></div>
<h2>
<a NAME="directories"></a>Layout of Directories</h2>
The source code is organized into several subdirectories within the Zoltan
main directory. General interface routines are stored
in a single directory. Communication and memory allocation utilities available
to all algorithms are in separate directories. Each load-balancing method
(or family of methods) should be stored in its own directory.
In addition, a courtesy copy of the
<a href="../ug_html/ug_alg_parmetis.html">ParMETIS</a>
graph-partitioning package is included in the top-level directory <i>ParMETIS</i>.
<p>
In the following
<a href="#directory table">table</a>,
the source-code directories currently in the Zoltan directory are listed
and described.
<br>&nbsp;
<table BORDER NOSAVE >
<tr>
<th><a NAME="directory table"></a>Directory</th>
<th>Description</th>
</tr>
<tr>
<td VALIGN=TOP><i>zz</i></td>
<td>General Interface definitions,
Zoltan data structure definitions, interface functions
and functions related to the interface
See <a href="dev_lb_interface.html">Interface Functions</a>,
<a href="dev_lb_types.html">ID Data Types</a>, and
<a href="dev_lb_structs.html">Data Structures</a>.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>lb</i></td>
<td>Load-Balancing interface routines,
and load-balancing data structure definitions.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>all</i></td>
<td><a href="dev_add_memory.html">Special memory allocation functions</a> for memory returned by Zoltan to an application.&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP><i>par</i></td>
<td><a href="dev_services_parallel.html">Parallel computing routines</a>.</td>
</tr>
<tr>
<td VALIGN=TOP><i>param</i></td>
<td><a href="dev_services_params.html">Routines for changing parameter values</a> at runtime.</td>
</tr>
<tr>
<td><i>parmetis</i></td>
<td>Routines to access the <a href="../ug_html/ug_alg_parmetis.html">ParMETIS</a>
and <a href="../ug_html/ug_alg_jostle.html">Jostle</a>
partitioning libraries.</td>
</tr>
<tr>
<td VALIGN=TOP><i>rcb</i></td>
<td><a href="../ug_html/ug_alg_rcb.html">Recursive Coordinate Bisection (RCB)</a> and
<a href="../ug_html/ug_alg_rib.html">Recursive Inertial Bisection (RIB)</a> algorithms.</td>
</tr>
<tr>
<td VALIGN=TOP><i>hsfc</i></td>
<td><a href="../ug_html/ug_alg_hsfc.html">Hilbert Space-Filling Curve partitioning</a>
algorithm.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>bsfc</i></td>
<td>Binned Space-Filling Curve partitioning algorithm.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>oct</i></td>
<td>Rensselaer Polytechnic Institute's <a href="../ug_html/ug_alg_oct.html">octree partitioning</a> algorithms.
</td>
</tr>
<tr>
<td><i>reftree</i></td>
<td>William Mitchell's <a href="../ug_html/ug_alg_reftree.html">Refinement Tree Partitioning</a>
algorithm and refinement tree data structure.</td>
</tr>
<tr>
<td><i>timer</i></td>
<td><a href="dev_services_time.html">Timing</a> routines.</td>
</tr>
<tr>
<td VALIGN=TOP><i>ch</i></td>
<td>Routines to read <a href="http://cs.sandia.gov/CRF/chac.html">Chaco</a>
input files and build graphs for the driver program <i><a href="dev_driver.html">zdrive.</a></i></td>
</tr>
<tr>
<td VALIGN=TOP><i>ha</i></td>
<td>Routines to support heterogeneous architectures.</td>
</tr>
<tr>
<td VALIGN=TOP><i>fort</i></td>
<td><a href="../ug_html/ug_fortran.html">Fortran (F90) interface</a> for Zoltan.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE><i>Utilities/shared</i></td>
<td VALIGN=TOP NOSAVE>Simple functions and utilities shared by Zoltan and
other Zoltan Utilities.
</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE><i>Utilities/Memory</i></td>
<td VALIGN=TOP NOSAVE><a href="../ug_html/ug_util_mem.html">Memory management utilities</a></td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE><i>Utilities/Communication</i></td>
<td VALIGN=TOP NOSAVE><a href="../ug_html/ug_util_comm.html">Unstructured communication
utilities</a></td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE><i>Utilities/DDirectory</i></td>
<td VALIGN=TOP NOSAVE><a href="../ug_html/ug_util_dd.html">Distributed Data Directory
utilities</a></td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE><i>Utilities/Config</i></td>
<td VALIGN=TOP NOSAVE><a href="../ug_html/ug_usage.html#Building the Library">Platform-specific
makefile definitions</a> for compiler, library and include-file paths.</td>
</tr>
<tr>
<td><i>driver</i></td>
<td>Test driver programs, <i><a href="dev_driver.html">zdrive</a></i> and
<i><a href="dev_driver.html">zCPPdrive</a></i>.</td>
</tr>
<tr>
<td VALIGN=TOP><i>fdriver</i></td>
<td>Fortran90 version of the <a href="dev_driver.html">test driver</a> program.</td>
</tr>
<tr>
<td VALIGN=TOP><i>examples</i></td>
<td>Simple examples written in C and C++ that use Zoltan. </td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE><i>docs/Zoltan_html</i></td>
<td>Zoltan documentation and <a href="../Zoltan.html">home page</a>.</td>
</tr>
<tr>
<td><i>docs/Zoltan_html/ug_html</i></td>
<td><a href="../ug_html/ug.html">User's guide</a> in HTML format.</td>
</tr>
<tr>
<td><i>docs/Zoltan_html/dev_html</i></td>
<td><a href="dev.html">Developer's guide</a> in HTML format.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE><i>docs/Zoltan_pdf</i></td>
<td>PDF versions of the Zoltan User's Guide and Developer's Guide.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE><i>docs/internal</i></td>
<td>SQA documents for the Zoltan project.</td>
</tr>
<caption ALIGN=BOTTOM><i>The directory structure of the Zoltan distribution.</i></caption>
</table>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_dist_compile.html">Next:&nbsp;
Compilation</a>&nbsp; |&nbsp; <a href="dev_dist_cvs.html">Previous:&nbsp;
CVS</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

170
thirdParty/Zoltan/docs/dev_html/dev_driver.html vendored Normal file
View File

@ -0,0 +1,170 @@
<!-------- @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: Using Test Drivers: zdrive and zfdrive</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_view.html">Next</a>&nbsp; |&nbsp; <a href="dev_refs.html">Previous</a></i></b></div>
<h2>
<a NAME="Zdrive"></a>Appendix: Using the Test Drivers: <i>zdrive</i>, <i>zCPPdrive</i> and <i>zfdrive</i></h2>
<h3>
<a NAME="Introduction"></a>Introduction</h3>
In order to facilitate development and testing of the Zoltan library,
simple driver programs, <i>zdrive</i> (C), <i>zCPPdrive</i> (C++)
and <i>zfdrive</i> (Fortran90),
are included with the library
distribution. The concept behind the drivers is to read in mesh or graph
information from files, run Zoltan, and then output the new assignments
for each processor to another file. The test drivers <i>zdrive</i>
and <i>zCPPdrive</i> read ExodusII/NemesisI
parallel FEM files, <a href="http://cs.sandia.gov/CRF/chac.html">Chaco</a>
input files, or <a href="https://math.nist.gov/MatrixMarket/">general
Matrix-Market</a> files.
Parallel NemesisI files can be created from ExodusII or Genesis
file using the NemesisI utilities <i>nem_slice</i> and <i>nem_spread</i>.
The Fortran90 program <i>zfdrive</i> reads only <a href="http://cs.sandia.gov/CRF/chac.html">Chaco</a> input files
and <a href="https://math.nist.gov/MatrixMarket/">general Matrix-Market</a>
files.
<p>
Source code for <i>zdrive</i> is in
the <i>driver</i> and <i>ch</i> directories of
the Zoltan distribution.
The source code for <i>zCPPdrive</i> is also in <i>driver</i>, and uses some
of the same C source files (in <i>driver</i> and <i>ch</i>) that <i>zdrive</i> uses.
Source code for <i>zfdrive</i> is in the <i>fdriver</i> directory.
<p>
The C and C++ test drivers are built automatically in the
<a href="../ug_html/ug_usage.html#Autotools">Autotools</a> build system.
The F90 driver is built when the configure option "--enable-f90interface" is
provided. The drivers are placed in <i>BUILD_DIR/src/driver</i> and
<i>BUILD_DIR/src/fdriver</i>, for build directory <i>BUILD_DIR</i>.
<p>
The C and C++ test drivers are built in the
<a href="../ug_html/ug_usage.html#CMake">CMake</a> build system when
option "-D Zoltan_ENABLE_Tests:BOOL=ON" is provided. The F90 driver is
built when option "-D Zoltan_ENABLE_F90INTERFACE:BOOL=ON" is also provided.
The drivers are placed in <i>BUILD_DIR/packages/zoltan/src/driver</i> and
<i>BUILD_DIR/packages/zoltan/src/fdriver</i>; they are also copied to
<i>BUILD_DIR/packages/zoltan/test</i>.
<h3>
<a NAME="running zdrive"></a>Running the Test Drivers</h3>
The test drivers are run using an input command file. A fully commented example of
this file and the possible options can be found in <i><a href="zdrive.inp">zdrive.inp</a></i>.
The default name for the command file is <i>zdrive.inp</i>, and the drivers will
look for this file in the execution directory if an alternate name is not
given on the command line. If another filename is being used for the command
file, it should be specified as the first argument on the command line.
(Note: <i>zfdrive</i> cannot read a command line argument; its input file
must be named <i>zdrive.inp</i>.)
<p>
For an example of a simple input file, see the <a href="#zdrive input">figure</a>
below. In this problem, the method being used for dynamic load balancing
is <a href="dev_rcb.html#RCB">RCB</a>.&nbsp; Input data is read from <a href="http://cs.sandia.gov/CRF/chac.html">Chaco</a>
input files<i> simple.graph</i> and <i>simple.coords</i>.&nbsp; Zoltan's
<a href="../ug_html/ug_param.html#Debug Levels in Zoltan">DEBUG_LEVEL</a> parameter
is set to 3; default values of all other parameters are used.
(Note: <i>zfdrive</i> can read only a simplified version of the input file.
See the <i>zfdrive</i> notes in <i><a href="zdrive.inp">zdrive.inp</a></i> for more details.)
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr VALIGN=TOP>
<td><a NAME="zdrive input"></a>
<tt>
Decomposition method&nbsp; = rcb
<br>Zoltan Parameters&nbsp;&nbsp;&nbsp;&nbsp; = Debug_Level=3
<br>File Type&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
= Chaco
<br>File Name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
= simple
<br>Parallel Disk Info&nbsp;&nbsp;&nbsp; = number=0
</tt>
</td>
</tr>
<caption ALIGN=BOTTOM><i><font size=-1>Example zdrive.inp file</font></i></caption>
</table></center>
<p>The <i>zdrive</i> programs creates ascii files named
"<i>file_name</i>.out.<i>p</i>.<i>n</i>", where <i>file_name</i>
is the file name specified in <i>zdrive.inp</i>, <i>p</i> is the number
of processors on which <i>zdrive</i> was run, and <i>n</i>=0,1,...,<i>p</i>-1 is
the processor by which the file was created. (For <i>zfdrive</i>, the
files are named "<i>file_name</i>.fout.<i>p</i>.<i>n</i>".)
These files are in the same directory where the input graph
file was located for that processor. Each file contains a list of global
ids for the elements that are assigned to that processor after running Zoltan.
The input decomposition can also be written in this format to files
"<i>file_name</i>.in.<i>p</i>.<i>n</i>";
see "zdrive debug level" in <i><a href="zdrive.inp">zdrive.inp</a></i> for more details.
<p>
Decompositions for 2D problems can be written to files that can be plotted
by <a href="https://www.gnuplot.org/">gnuplot</a>. See "gnuplot output" in <i><a href="zdrive.inp">zdrive.inp</a></i>
for more information. Decompositions for 3D problems can be viewed after the
test driver has finished by running the graphical tools <I>vtk_view</I> or
<I>vtk_write</I> described <a href="dev_view.html">next</a>.
<h3>
<a NAME="adding algorithms"></a>Adding New Algorithms</h3>
The driver has been set up in such a way that testing new algorithms that
have been added to Zoltan is relatively simple. The method that is in the
input file is passed directly to Zoltan. Thus, this string must be the
same string that the parameter <a href="../ug_html/ug_alg.html#LB_METHOD"><i>LB_METHOD</i></a> is expecting.
<h3>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_view.html">Next:&nbsp;
Visualizing Geometric Partitions</a>&nbsp; |&nbsp; <a href="dev_refs.html">Previous:&nbsp;
References</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html

240
thirdParty/Zoltan/docs/dev_html/dev_fortran.html vendored Normal file
View File

@ -0,0 +1,240 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: FORTRAN Interface</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_cpp.html">Next</a>&nbsp; |&nbsp; <a href="dev_mig.html">Previous</a></i></b></div>
<H2>
<A NAME="fortran dev"></A>FORTRAN Interface</H2>
With any change to the user API of Zoltan, the Fortran interface should
be modified to reflect the change. This section contains information about
the implementation of the Fortran interface which should cover most situations.
<UL><A HREF="#fortran dev structures">Structures</A>
<BR><A HREF="#fortran dev modifications">Modifications to an existing Zoltan
interface function</A>
<BR><A HREF="#fortran dev remove">Removing a Zoltan interface function</A>
<BR><A HREF="#fortran dev add">Adding a new Zoltan interface function</A>
<BR><A HREF="#fortran dev query">Query functions</A>
<BR><A HREF="#fortran dev enum">Enumerated types and defined constants</A></UL>
If you have questions or need assistance, contact <A HREF="mailto:william.mitchell@nist.gov">william.mitchell@nist.gov</A>.
<P>If changes are made to functions that are called by <I><A HREF="dev_driver.html#Zdrive">zdrive</A></I>,
then the changes should also be made to
<a href="dev_driver.html"><I>zfdrive</I></a>. Changes to the
Fortran interface can be tested by building and running <a href="dev_driver.html"><I>zfdrive</I></a>,
if the changes are in functions called by <a href="dev_driver.html"><I>zfdrive</I></a>.
The <a href="dev_driver.html"><I>zfdrive</I></a> program
works the same way as <I><A HREF="dev_driver.html">zdrive</A></I>
except that it is restricted to the
<a href="http://cs.sandia.gov/CRF/chac.html">Chaco</a>
examples and simpler input files.
<P>Any changes in the interface should also be reflected in the Fortran
API definitions in the <A HREF="../ug_html/ug.html">Zoltan User's Guide</A>.
<H3>
<A NAME="fortran dev structures"></A>Structures</H3>
All structures in the API have a corresponding user-defined type in the
Fortran interface. If a new structure is added, then modifications will
be required to <I>fort/fwrap.fpp</I> and <I>fort/cwrap.c</I>. In these
files, search for <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>
and "do like it does."
<P>An explanation of how structures are handled may help. The Fortran user-defined
type for the structure simply contains the address of the structure, i.e.,
the C pointer returned by a call to create the structure. Note that the
user does not have access to the components of the structure, and can only
pass the structure to functions. Within the Fortran structure, the
address is stored in a variable of type(<B>Zoltan_PTR</B>), which is a character
string containing one character for each byte of the address. This gives
the best guarantee of portability under the Fortran and C standards. Also,
to insure portability of passing character strings, the character string
is converted to an array of integers before passing it between Fortran
and C. The process of doing this is most easily seen by looking at <B><A HREF="../ug_html/ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</A></B>,
which has little else to clutter the code.
<H3>
<A NAME="fortran dev modifications"></A>Modifications to an existing Zoltan
interface function</H3>
If the argument list or return type of a user-callable function in Zoltan
changes, the same changes must be made in the Fortran interface routines.
This involves changes in two files: <I>fort/fwrap.fpp</I> and <I>fort/cwrap.c</I>.
In these files, search for the function name with the prefix <B>Zoltan_ </B>omitted,
and modify the argument list, argument declarations, return type, and call
to the C library function as appropriate. When adding a new argument, if
there is not already an argument of the same type,&nbsp; look at another
function that does have an argument of that type for guidance.
<H3>
<A NAME="fortran dev remove"></A>Removing a Zoltan interface function</H3>
If a user callable function is removed from the Zoltan library, edit <I>fort/fwrap.fpp</I>
and <I>fort/cwrap.c</I> to remove all references to that function.
<H3>
<A NAME="fortran dev add"></A>Adding a new Zoltan interface function</H3>
Adding a new function involves changes to the two files <I>fort/fwrap.fpp</I>
and <I>fort/cwrap.c</I>. Perhaps the easiest way to add a new function
to these files is to pick some existing function, search for all occurrences
of it, and use that code as a guide for the implementation of the interface
for the new function. <B><A HREF="../ug_html/ug_interface_augment.html#Zoltan_LB_Point_Assign">Zoltan_LB_Point_Assign</A></B>
is a nice minimal function to use as an example. Use a case insensitive
search on the name of the function without the <B>Zoltan_LB_</B> prefix, for example
<B>point_assign</B>.
<P>Here are the items in <I>fwrap.fpp</I>:
<UL>
<LI>
public statement: The name of the function should be included in the list
of public entities.</LI>
<LI>
interface for the C wrapper: Copy one of these and modify the function
name, argument list and declarations for the new function. The name is
of the form <B>Zfw_LB_Point_Assign</B> (fw stands for Fortran wrapper).</LI>
<LI>
generic interface: This assigns the function name to be a generic name
for one or more module procedures.</LI>
<LI>
module procedure(s): These are the Fortran-side wrapper functions. Usually
there is one module procedure of the form <B>Zf90_LB_Point_Assign</B>. If
one argument can have more than one type passed to it (for example, it
is type void in the C interface), then there must be one module procedure
for each type that can be passed. These are distinguished by appending
a digit to the end of the module procedure name. If n arguments can have
more than one type, then n digits are appended. See <B><A HREF="../ug_html/ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</A></B>
for example. Generally the module procedure just calls the C-side wrapper
function,<B> </B>but in some cases it may need to coerce data to a different
type (e.g., <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>),
or may actually do real work (e.g., <B><A HREF="../ug_html/ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</A></B>).</LI>
<BR>&nbsp;</UL>
Here are the items in <I>cwrap.c</I>:
<UL>
<LI>
name mangling: These are macros to convert the function name from the case
sensitive C name (for example, <B>Zfw_LB_Point_Assign</B>) to the mangled
name produced by the Fortran compiler. There are four of these for each
function:</LI>
<UL>
<LI>
lowercase (<B>zfw_lb_point_assign</B>),</LI>
<LI>
uppercase (<B>ZFW_LB_POINT_ASSIGN</B>),</LI>
<LI>
lowercase with underscore (<B>zfw_lb_point_assign_</B>), and</LI>
<LI>
lower case with double underscore (<B>zfw_point_assign__</B> but the
second underscore is appended only if the name already contains an underscore,
which will always be the case for names starting with <B>Zfw_</B>).</LI>
</UL>
<LI>
C-side wrapper function: Usually this just calls the Zoltan library function
after coercing the form of the data (for example, constructing the pointer
to <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A> </B>and call-by-reference
to call-by-value conversions).</LI>
</UL>
<H3>
<A NAME="fortran dev query"></A>Query functions</H3>
If a query function is added, deleted or changed, modifications must be
made to <I>fort/fwrap.fpp</I> and <I>fort/cwrap.c</I>, similar to the modifications
for interface functions, and possibly also<I> include/zoltan.h</I> and <I>zz/zz_const.h</I>.
<P>Here are the places query functions appear in <I>fwrap.fpp</I>:
<UL>
<LI>
public statement for the <B><A HREF="dev_lb_interface.html#interface_fns">ZOLTAN_FN_TYPE</A></B>
argument: These are identical to the C enumerated type.</LI>
<LI>
definition of the <B><A HREF="dev_lb_interface.html#interface_fns">ZOLTAN_FN_TYPE</A></B>
arguments: There are two groups of these, one containing subroutines (void
functions) and one containing functions (int functions). Put the new symbol
in the right category. The value assigned to the new symbol must agree
exactly with where the symbol appears in the order of the enumerated type.</LI>
</UL>
Here are the places query functions appear in <I>cwrap.c</I>:
<UL>
<LI>
reverse wrappers: These are the query functions that are actually called
by the Zoltan library routines when the query function was registered from
Fortran. They are just wrappers to call the registered Fortran routine,
coercing argument types as necessary. Look at <B>Zoltan_Num_Edges_Fort_Wrapper</B>
for an example.</LI>
<LI>
<B>Zfw_Set_Fn</B>: This has a switch based on the value of the <B><A HREF="dev_lb_interface.html#interface_fns">ZOLTAN_FN_TYPE</A></B>
argument to set the Fortran query function and wrapper in the <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>.</LI>
</UL>
In <I>zz/zz_const.h</I>, if a new field is added to the structures for
a new query function, it should be added in both C and Fortran forms. In
<I>include/zoltan.h</I>, if a new typedef for a query function is added,
it should be added in both C and Fortran forms. See these files for examples.
<H3>
<A NAME="fortran dev enum"></A>Enumerated types and defined constants</H3>
Enumerated types and defined constants that the application uses as the
value for an arguments must be placed in<I> fwrap.fpp</I> with the same
value. See <B><A HREF="../ug_html/ug_interface.html#Error Codes">ZOLTAN_OK</A></B>
for an example.&nbsp;
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_cpp.html">Next:&nbsp;
C++ Interface</A>&nbsp; |&nbsp; <A HREF="dev_mig.html">Previous:&nbsp;
Migration Tools</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

133
thirdParty/Zoltan/docs/dev_html/dev_hier.html vendored Normal file
View File

@ -0,0 +1,133 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="Jim Teresco, jdteres@sandia.gov">
<TITLE> Zoltan Developer's Guide: HIER</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_rib.html">Next</a>&nbsp; |&nbsp; <a href="dev_test_script.html">Previous</a></i></b></div>
<H2>
<A NAME="HIER"></A>Appendix: Hierarchical Partitioning (HIER)</H2>
&nbsp;
<H3>
Outline of Algorithm</H3>
<P>Zoltan's hierarchical balancing automates the creation of hierarchical
partitions. The implementation of Hierarchical Partitioning (HIER) in Zoltan is
due to Jim Teresco (Williams College), with many suggestions and ideas
from the entire Zoltan team.<P>
The hierarchical balancing implementation utilizes a lightweight
intermediate structure and a set of callback functions that permit an
automated and efficient hierarchical balancing which can use any of
the procedures available within Zoltan without modification and in any
combination. Hierachical balancing is invoked by an application the
same way as other Zoltan procedures. Since Zoltan is data-structure
neutral, it operates on generic "objects" and interfaces with
applications through callback functions.<P>
A hierarchical balancing step begins by building an intermediate
structure using the application-supplied callbacks. The initial
structure is computed using <B>Zoltan_Build_Graph</B> to build the
same structure that is used to support partitioning using the Parmetis
and Jostle libraries. The hierarchical balancing procedure then
provides its own callback functions to allow existing Zoltan
procedures to be used to query and update the intermediate structure
at each level of a hierarchical balancing. The structure is augmented
to keep track of objects and their needed information during the
procedure. After all levels of the hierarchical balancing have been
completed, Zoltan's usual migration arrays are constructed and
returned to the application. Thus, only lightweight objects are
migrated internally between levels, not the (larger and more costly)
application data. More details about the fields of the intermediate
structure and how the are used can be found in the Zoltan distribution
in <I>hier/README</I>.<P>
<BR>&nbsp;
<H3>
Data Structure Definitions</H3>
<P>There is one major data structure in HIER, defined in
<i>hier/hier.h</i>. The <I>struct HierPartParamsStruct</I> includes
all information needed by the hierarchical balancing procedures. The
fields are documented in comments in the structure definition.
<BR>&nbsp;
<H3>
Parameters</H3>
<P>The parameters used by HIER and their default values are described in the
<a href="../ug_html/ug_alg_hier.html">HIER section</a> of the <B><A HREF="../ug_html/ug.html">Zoltan User's
Guide</A></B>. These can be set by use of the <b>Zoltan_Hier_Set_Param</b> subroutine
in the file <i>hier/hier.c</i>.
<BR>&nbsp;
<H3>
Main Routine</H3>
<P>The main routine for HIER is <b>Zoltan_Hier</b> in the file <i>hier/hier.c</i>.
<BR>&nbsp;
<BR>&nbsp;
<BR>&nbsp;
<P>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of
Contents</A>&nbsp; |&nbsp; <a href="dev_rib.html">Next:&nbsp;
Recursive Inertial Bisection (RIB)</a>&nbsp; |&nbsp; <A HREF="dev_test_script.html">
Previous:&nbsp; Using the Test Script</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

298
thirdParty/Zoltan/docs/dev_html/dev_hsfc.html vendored Normal file
View File

@ -0,0 +1,298 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 5.6 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: HSFC</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_degenerate.html">Next</a> &nbsp;
|&nbsp; <a href="dev_reftree.html">Previous</a></i></b></div>
<H2>
<A NAME="HSFC"></A>Appendix: Hilbert Space Filling Curve (HSFC)</H2>
&nbsp;
<H3>
Outline of Algorithm</H3>
This partitioning algorithm is loosely based on the 2D & 3D Hilbert tables used in Octree
and on the BSFC partitioning implementation by Andrew C. Bauer, Department of
Engineering, State University of New York at Buffalo, as his summer project at
SNL in 2001. Please refer to the corresponding section in the Zoltan User's guide,
<a href="../ug_html/ug_alg_hsfc.html"><b>Hilbert Space Filling Curve (HSFC),</b></a>
for information about how to use this module and its parameters. Note: the partitioning,
point assign and box assign functions in this code module can be trivially extended
to any space filling curve for which we have a state table definition of the curve.
<p>
First, the weights and inverse Hilbert coordinates for each object
are determined. If the objects do not have weights, unit weights are assigned.
If the objects have multiple weights, only the first weight is currently used. The smallest
axis-aligned box is found that contains
all of the objects using their two or three dimensional spatial coordinates.
This bounding box is slightly expanded to ensure that all objects are strictly
interior to the boundary surface. The bounding box is necessary in order to calculate
the inverse Hilbert Space Filling curve coordinate. The bounding box is used to
scale the problem coordinates into the [0,1]^d unit volume (d represents the number of dimensions
in the problem space.) The inverse Hilbert
coordinate is calculated and stored as a double precision floating point value for
each object. This code works on problems with one, two or three dimensions (the
1-D Inverse Hilbert coordinate is simply the problem coordinate itself, after the
bounding box scaling.)
<p>
The algorithm seeks to cut the unit interval into P segments containing equal
weights of objects associated to the segments by their inverse Hilbert coordinates.
The code allows a user vector to specify the desired fraction
of the total weight to be assigned to each interval. Note, a zero weight fraction prevents any object
being assigned to the corresponding interval. The unit interval is divided into N bins,
N=k(P-1)+1, where k is a
small positive constant.) Each bin has an left and right endpoint
specifying the half-open interval [l,r) associated with the bin. The bins form a
non-overlapping cover of [0,1] with the right endpoint of the last bin forced to include 1.
The bins are of equal size on the first loop. (Hence each interval or part of the
partition is a collection of bins.)
<p>
For each loop, an MPI_Allreduce call is made to
globally sum the weights in each bin. This call also determines the maximum and
minimum (inverse Hilbert) coordinate found in each bin. A greedy algorithm sums the
weights of the bins from left to right until the next bin would cause an overflow for
the current part. This results in new partition of P intervals. The location of
each cut (just before an "overflowing" bin) and the size of its "overflowing" bin are
saved. The "overflowing" bin's maximum and minimum are compared to determine if the bin
can be practically subdivided. (If the bin's maximum and minimum coordinates are too
close relative to double precision resolution, the bin can not be practically
subdivided.) If at least one bin can be further refined, then looping will continue.
In order to prevent a systematic bias, the greedy algorithm is assumed to exactly
satisfy the weight required by each part.
<p>
Before starting the next loop, the P intervals are again divided into N bins. The
P-1 "overflow" bins are each subdivided into k-1 equal bins. The
intervals before and after these new bins determine the remaining bins. This process
maintains a fixed number of bins. No bin is "privileged." Specifically, any bin is
subject to later refinement, as necessary, on future loops.
<p>
The loop terminates when there is no need to further divide any "overflow" bin. A slightly
different greedy algorithm is used to determine the final partition of P intervals from the
N bins. In this case, when the next bin would cause an overflow, the tolerance
is computed for both underfilling (excluding this last bin) and overfilling
(including the last bin). The tolerance closest to the target tolerance is
used to select the dividing point. The tolerance obtained at each dividing
point is compared to the user's specified tolerance. An error is returned if
the user's tolerance is not satisfied at any cut. After each cut is made, a
correction is calculated as the ratio of the actual weight to the target
weight used up to this point. This correction is made to the target weight
for the next part. This correction fixes the subsequent parts when
a "massive" weight object is on the border of a cut and its assignment creates an
excessive imbalance.
<p>
Generally, the number of loops is small (proportional to log(number of objects)).
A maximum of MAX_LOOPS is
used to prevent an infinite looping condition. A user-defined
function is used in the MPI_Allreduce call in order to simultaneously determine the
sum, maximum, and minimum of each bin. The message length in the MPI_Allreduce is
proportional to the P, the number of parts.
<p>
Note, when a bin is encountered that satisfies more than two parts, that bin is refined
into a multiple of k-1 intervals which maintains a total of N bins.
<BR>&nbsp;
<h3>Hilbert Transformations</h3>
The HSFC now uses table driven logic to convert from spatial coordinates (2 or 3 dimensions)
(the Inverse Hilbert functions) and from the unit interval into spatial coordinates
(Hilbert functions). In each case there are two associated tables: the data table and the
state table. In all cases, the table logic can be extended to any required precision. Currently,
the precision is determined for compatibility with the the double precision used in
the partitioning algorithm.
<p>The inverse transformation is computed by taking the highest order bit from each spatial
coordinate and packing them together as 2 or 3 bits (as appropriate to the dimensionality)
in the order xyz (or xy) where x is the highest bit in the word.
The initial state is 0. The data table lookup finds the value
at the column indexed by the xyz word and the row 0 (corresponding to the initial state value.)
This data are the 3 (or 2) starting bits of the Hilbert coordinate. The next state value
is found by looking up the corresponding element of the state table (xyz column and row 0.)
<p>
The table procedure continues to loop (using loop counter i, for example) until the required
precision is reached. At loop i, the ith bits from each spatial dimension are packed together
as the xyz column index. The data table lookup finds the element at column xyz and the row
determined by the last state table value. This is appended to the Hilbert coordinate. The
state table is used to find the next state value at the element corresponding to the xyz
column and row equal to the last state value.
<p>
The inverse transformation is analogous. Here the 3 (or 2 in the 2-d case) bits of the
Hilbert coordinate are extracted into a word. This word is the column index into the
data table and the state value is the row. This word found in the data table is
interpreted as the packed xyz bits for the spatial coordinates. These bits are
extracted for each dimension and appended to that dimension's coordinate. The corresponding
state table is used to find the next row (state) used in the next loop.
<BR>&nbsp;
<h3>Point Assign</h3>
The user can use
<a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Point_Assign"><b>Zoltan_LB_Point_Assign</b></a>
to add a new point to the
appropriate part. The bounding box coordinates,
the final partition, and other related information are maintained after partitioning if the KEEP_CUTS
parameter is set by the user. The KEEP_CUTS parameter must be set by the user for Point Assign!
The extended bounded box is
used to compute the new point's inverse Hilbert coordinate. Then the
routine performs a binary search on the final partition to determine the part (interval) which
includes the point. The routine returns the part number assigned to that
interval.
<p>
The Point Assign function now works for any point in space, even if the point is
outside the original bounding box. If the point is outside the bounding box, it is first
scaled using the same equations that scale the interior points into the unit volume.
The point is projected onto the unit volume. For each spatial dimension, if the scaled
coordinate is less than zero, it is replace by zero. If it is greater than one, it is
replaced by one. Otherwise the scaled coordinate is directly used.
<BR>&nbsp;
<h3>Box Assign</h3>
The user can use
<a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Box_Assign"><b>Zoltan_LB_Box_Assign</b></a>
to determine the parts whose
corresponding subdomains intersect the user's query box.
Although very different in implementation, the papers by Lawder and King ("Querying Multi-
dimensional Data Index Using the Hilbert Space-Filling Curve", 2000, etc.) were the original
inspiration for this algorithm. The Zoltan_HSFC_Box_Assign routine primarily scales the
user query region and determines its intersection with the Hilbert's bounding box. Points
exterior to the bounding box get projected along the coordinate axis onto the bounding box.
A fuzzy region is built around query points and lines to create the boxes required for the search.
It also handles the trivial one-dimensional case. Otherwise it repeatedly calls the 2d and 3d
query functions using the next highest part's left end point to start the search. These query
routines return the next point on the Hilbert curve to enter the query region. A binary
search finds the part associated with this point. The query functions are called one more
time than the number of parts that have points interior to the query region.
<p>
The query functions decompose the unit square (or cube) level by level like the Octree method.
Each level divides the remaining region into quadrants (or octets in 3d). At each level, the
quadrant with the smallest inverse Hilbert coordinate (that is, occurring first along the Hilbert curve)
whose inverse Hilbert coordinate is equal or larger than the starting inverse Hilbert coordinate and which
intersects with query region is selected. Thus, each level calculates the next 2 bits
(3 bits in 3d) of the inverse Hilbert coordinate of the next point to enter the query region. No more
than once per call to the query function, the function may backtrack to a nearest previous
level that has another quadrant that intersects the query region and has a higher Hilbert coordinate.
<p>
In order to determine the intersection with the query region, the next 2 bits (3 in 3 dimensions) of
the Hilbert transformation
are also computed (by table lookup) at each level for the quadrant being tested. These bits are
compared to the the bits resulting from the intersection of the query region with the region
determined by the spatial coordinates computed to the precision of the previous levels.
<p>
If the user query box has any side (edge) that is "too small" (effectively degenerate in
some dimension), it is replaced by a minimum value and the corresponding vertex coordinates
are symmetrically expanded. This is refered to as a "fuzzy" region.
<p>
This function requires the KEEP_CUTS parameter to be set by the user.
The Box Assign function now works for any box in space, even if it has regions outside the
original bounding box. The box vertices are scaled and projected exactly like the points
in the Point Assign function described above. However, to allow the search to use a proper
volumn, projected points, lines, and planes are converted to a usable volume by the
fuzzy region process described above.
<p>
This algorithm will work for any space filling curve. All that is necessary is to
provide the tables (derieved from the curve's state transition diagram) in place of
the Hilbert Space Filling Curve tables.
<BR>&nbsp;
<H3>Data Structure Definitions</H3>
The data structures are defined in <i>hsfc/hsfc.h</i>. The objects being load balanced
are represented by the <i>Dots</i> Structure which holds the objects spacial coordinates,
the corresponding inverse Hilbert coordinate, the processor owning the object,
and the object's weight(s). The <i>Partition</i> structure holds the left and right
endpoints of the interval represented by this element of the partition and the index
to the processor owning this element of the partition. The structure <i>HSFC_Data</i>
holds the "persistant" data
needed by the point assign and box assign routines. This includes the bounding box,
the number of loops necessary for load balancing, the number of dimensions for the problem,
a pointer to the function that returns the inverse Hilbert Space-Filling Curve
coordinate, and the final Partition structure contents.
<P>
<H3>
Parameters</H3>
<P>The parameters used by HSFC and their default values are described in the
<a href="../ug_html/ug_alg_hsfc.html">HSFC section</a> of the <B><A HREF="../ug_html/ug.html">Zoltan User's
Guide</A></B>. These can be set by use of the <b>Zoltan_HSFC_Set_Param</b> subroutine
in the file <i>hsfc/hsfc.c</i>.
<p>
When the parameter <a href="../ug_html/ug_alg_hsfc.html">REDUCE_DIMENSIONS</a>
is specified, the HSFC algorithm will perform lower dimensional
partitioning if the geometry is found to be degenerate. More information
on detecting degenerate
geometries may be found in another <a href="dev_degenerate.html">
section</a>.
<BR>&nbsp;
<H3>
Main Routine</H3>
<P>The main routine for HSFC is <b>Zoltan_HSFC</b> in the file <i>hsfc/hsfc.c</i>.
<BR>&nbsp;
<BR>&nbsp;
<BR>&nbsp;
<P>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp;
|&nbsp; <a href="dev_degenerate.html">Next: &nbsp; Handling Degenerate Geometries</a>
|&nbsp; <A HREF="dev_reftree.html"> Previous:&nbsp; Refinement Tree</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

82
thirdParty/Zoltan/docs/dev_html/dev_intro.html vendored Normal file
View File

@ -0,0 +1,82 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: Introduction</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_intro_philosophy.html">Next</a>&nbsp; |&nbsp; <a href="dev.html">Previous</a></i></b></div>
<H2>
<A NAME="intro"></A>Introduction and General Principles</H2>
The goal of the Zoltan project is to design a general-purpose tool for
parallel data management for unstructured, dynamic applications.&nbsp; This tool includes a suite of load-balancing
algorithms, an unstructured communication package, distributed data directories, and dynamic debugging tools that can be used by a variety of applications.&nbsp; It will, thus,
be used by many application developers and be added to by many algorithm
developers.&nbsp; Software projects of this scale need general guidelines
and principles so that the code produced is easily maintained and added
to.&nbsp; We have tried to keep restrictions on developers to a minimum.&nbsp;
However, we do require that a few coding practices be followed.&nbsp; These
guidelines are described in the following sections:
<BLOCKQUOTE><A HREF="dev_intro_philosophy.html">Philosophy of Zoltan</A>
<BR><A HREF="dev_intro_coding.html">Coding Principles in Zoltan</A>
<BR><A HREF="dev_intro_sqe.html">Zoltan Quality Assurance</A>
</BLOCKQUOTE>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_intro_philosophy.html">Next:&nbsp;
Philosophy of Zoltan</A>&nbsp; |&nbsp; <A HREF="dev.html">Previous:&nbsp;
Table of Contents</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

255
thirdParty/Zoltan/docs/dev_html/dev_intro_coding.html vendored Normal file
View File

@ -0,0 +1,255 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 5.6 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: Coding Principles</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_intro_sqe.html">Next</a>&nbsp; |&nbsp; <a href="dev_intro_philosophy.html">Previous</a></i></b></div>
<H2>
<A NAME="coding"></A>Coding Principles in Zoltan</H2>
<blockquote>
<ol TYPE=A><a href="#include">Include files</a>
<br><a href="#global">Global Variables</a>
<br><a href="#functions">Function Names</a>
<br><a href="#par_comm">Parallel Communication</a>
<br><a href="#memory1">Memory Management</a>
<br><a href="#return">Errors, Warnings and Return Codes</a>
</ol>
</blockquote>
<H3>
<A NAME="include"></A>Include files</H3>
Include files should be used for function prototypes, macro definitions,
and data structure definitions. The convention used is that external function
prototypes and data structure definitions
required by more than one module are stored in include files named
<I>*_const.h</I> (e.g., <I>zz/zz_const.h</I>). Include files with static
function prototypes or static data structure
definitions (i.e., files that are included in only one module) are
named <I>*.h</I> (e.g.,<I> rcb/rcb.h</I>).
<P>The include file <I>include/zoltan.h</I> contains the Zoltan
interface; it should be included by C application source files that call
Zoltan. C++ applications that use the C++ interface should include
<I>include/zoltan_cpp.h</I> instead.
<p>
The include file <I>zz/zz_const.h</I> describes
the principle Zoltan data structures. As these data structures
are used heavily by the algorithms in Zoltan, <I>zz/zz_const.h</I>
should be included in most source files of Zoltan.
<p>
Every Zoltan C language header file should be surrounded with an
<B>extern "C" {}</B> declaration. The declaration must occur after
every other <B>#include</B> statement, and before all function
declarations.
This declaration tells a C++ compiler not to
mangle the names of functions declared in that header file.
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR>
<TD><A NAME="extern C"></A>
<TT>
#ifndef __EXAMPLE_H<br>
#define __EXAMPLE_H<br><br>
#include "mpi.h"<br>
#include "zoltan_types.h"<br>
#include "zoltan_align.h"<br><br>
#ifdef __cplusplus<br>
extern "C" {<br>
#endif<br><br>
int func1(int a, int b);<br>
double dfunc(int a, int b, int c);<br><br>
#ifdef __cplusplus<br>
} /* closing bracket for extern "C" */<br>
#endif<br><br>
#endif /* __EXAMPLE_H */<br>
</TT>
</TR>
<CAPTION ALIGN=BOTTOM><I>Example of C language header file with <b>extern "C"</b>
</I></CAPTION>
</TABLE></CENTER>
<br>
<p>
If an <B>#include</B> statement appears after the opening of the
<B>extern "C" {}</B> declaration, the included file may cause
<B>mpi.h</B> or some other system header file to be processed. When
compiling with a C++ compiler, this usually leads to compile errors
because the function names in some of those headers are supposed to be
mangled.
<p>
It should
not be necessary to use the declaration in all header files, but
rather only in header files that are used in C++ applications. But
experience has taught us that you never know what header files will
end up being included, and that one that is not included now, may be
included in the future when someone adds an <B>#include</b> statement
to a file. To save someone the effort later on of figuring out
why their C++ compilation is failing, please include the
<B>extern "C" {}</B> declaration in every header file, even if at
this point in time you do not believe it will ever be included in
the compilation of a C++ application.
<BR>&nbsp;
<H3>
<A NAME="global"></A>Global variables</H3>
The use of global variables is highly discouraged in Zoltan.
In limited cases, static global variables can be tolerated within
a source file of an algorithm. However, developers should keep in mind
that several Zoltan structures may be used by an application, with
each structure using the same algorithm. Thus, global variables set by one
invocation of a routine may be reset by other invocations, causing errors
in the algorithms. Global variable names may also conflict with variables
used elsewhere in the library or application, causing unintended side-effects
and complicating debugging. For greatest robustness, developers are asked
NOT to use global variables in their algorithms. See <A HREF="dev_add_struct.html">Data
Structures</A> for ideas on avoiding the use of global variables.
<BR>&nbsp;
<H3>
<A NAME="functions"></A>Function Names</H3>
In order to avoid name conflicts with applications and other libraries,
all non-static functions should be prepended with <B>Zoltan_</B><I>.</I>&nbsp;
Moreover, function names should, in general, include their module names; e.g.,
<b>Zoltan_HSFC_Box_Assign</b> is part of the HSFC module of Zoltan.
As a general
rule, each new word in a function name should be capitalized (for example,
<b>Zoltan_Invert_Lists</b>).
Static Zoltan functions do not have to follow these rules.
<H3>
<A NAME="par_comm"></A>Parallel Communication</H3>
All communication in the Zoltan library should be performed through MPI
communication routines. The MPI interface was chosen to enable portability
to many different platforms. It will be especially important as the code
is extended to heterogeneous computing systems.
<P>Some useful communication utilities are provided within the library
to perform unstructured communication and synchronization. See <A HREF="../ug_html/ug_util_comm.html">Unstructured
Communication Utilities</A> and <A HREF="dev_services_parallel.html">Parallel
Computing</A>.
<BR>&nbsp;
<H3>
<A NAME="memory1"></A>Memory Management</H3>
It is strongly suggested that all memory allocation in the library is handled
using the functions supplied in <I>Utilities/Memory</I>. Use of these functions
will make debugging and maintenance of the library much easier as the library
gets larger. See <A HREF="../ug_html/ug_util_mem.html">Memory Management Utilities</A> for
more information on these utilities.<p>
For memory that is returned by Zoltan to an application, however, special
memory allocation functions must be used to maintain compatibility with
both C and Fortran90 applications. See <a href="dev_add_memory.html">
Memory Management in Zoltan Algorithms</a> for more
information. <p>
One of the few data types specified for use in the Zoltan interface is the
<a href="../ug_html/ug_usage.html#Data Types for Object IDs"><b>ZOLTAN_ID_PTR</b></a>
type used for global and local object identifiers (IDs). Macros simplifying
and providing error checking for
<a href="dev_lb_types.html">ID allocation and manipulation</a>
are provided.
<BR>&nbsp;
<H3>
<A NAME="return"></A>Errors, Warnings, and Return Codes</H3>
If an error or warning occurs in the Zoltan library,
a message should be printed to
<i>stderr</i> (using one of the <a href="#ZOLTAN_PRINT">printing macros</a> below),
all memory allocated in the current function should be freed, and
an <a href="../ug_html/ug_interface.html#Error Codes">error code</a> should be returned.
The Zoltan library should never "exit";
control should always be returned to the application with an error code.
The <a href="../ug_html/ug_interface.html#Error Codes">error codes</a> are defined in <i>include/zoltan_types.h</i>.
<p>
Currently, this philosophy is not strictly followed in all portions
of Zoltan.
Efforts are underway to bring existing code up-to-date, and to follow this
rule in all future development.
<BR>&nbsp;
<hr><a NAME="ZOLTAN_PRINT"></a>
<b>ZOLTAN_PRINT_ERROR</b>(int <i>processor_number</i>, char *<i>function_name</i>, char *<i>message</i>)<br>
<b>ZOLTAN_PRINT_WARN</b>(int <i>processor_number</i>, char *<i>function_name</i>, char *<i>message</i>)<br>
<hr>
Macros for printing error and warning messages in Zoltan. The macros are
defined in <i>Utilities/shared/zoltan_util.h</i>.
<TABLE WIDTH="100%" NOSAVE>
<TR>
<TD VALIGN=TOP WIDTH="20%"><b>Arguments:</b></TD>
<TD WIDTH="80%" ALIGN=LEFT></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp;&nbsp;<i>processor_number</i></TD>
<TD ALIGN=LEFT> The processor's rank in the Zoltan communicator. The value -1 can be used if the rank is not available.</td>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp;&nbsp;<i>function_name</i></TD>
<TD ALIGN=LEFT> A string containing the name of the function in which the error or warning occurred. </td>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp;&nbsp;<i>message</i></TD>
<TD ALIGN=LEFT> A string containing the error or warning message.</td>
</TR>
</table>
<hr>
<p>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_intro_sqe.html">Next:&nbsp;
Zoltan Quality Assurance</A>&nbsp; |&nbsp; <A HREF="dev_intro_philosophy.html">Previous:&nbsp;
Philosophy</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

91
thirdParty/Zoltan/docs/dev_html/dev_intro_philosophy.html vendored Normal file
View File

@ -0,0 +1,91 @@
<!-------- @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: Philosophy</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_intro_coding.html">Next</a>&nbsp; |&nbsp; <a href="dev_intro.html">Previous</a></i></b></div>
<h2>
<a NAME="philosophy"></a>Philosophy of Zoltan</h2>
The Zoltan library is designed to be a general-purpose tool-kit
providing a variety of parallel data management services to a wide range
of scientific applications (see the <a href="../ug_html/ug.html">Zoltan
User's Guide</a>). To enable general use of the library, the library does
not directly access the data structures of an application. Instead, the
library obtains information it needs through
an object-oriented interface between Zoltan and the
application.
This interface uses call-back query functions to gather information. An
application developer must write and register these query functions before
using Zoltan. The intent, however, is that the number
and complexity of these query functions are low, allowing applications
to easily interface with the library. In addition, new algorithm
development would use the same query functions as previous algorithms,
enabling applications to use new algorithms without changes to the query
functions.
<p>In developing new algorithms for Zoltan, the developer
must write the code that calls the query functions to build the needed
data structures for the algorithm. However, the application need not change
its query functions. Thus, new algorithms can be added to the library and
used by an application with minimal effort on the part of the application
developer.
<p>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_intro_coding.html">Next:&nbsp;
Coding Principles</a>&nbsp; | <a href="dev_intro.html">Previous:&nbsp;
Introduction</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

389
thirdParty/Zoltan/docs/dev_html/dev_intro_sqe.html vendored Normal file
View File

@ -0,0 +1,389 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE>Zoltan Developer's Guide: Quality Program</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a> |
<a href="dev_dist.html">Next</a> | <a href="dev_intro_coding.html">Previous</a></i></b></div>
<H2>
<A NAME="SQE"></A>Zoltan Quality Assurance</H2>
This document describes the Software Quality Assurance (SQA)
policies and procedures used in the Zoltan project. Zoltan developers
at Sandia or under contract to Sandia are required to follow these
software development policies.
<blockquote>
<a href="#Quality_Policy">Quality Policy</a>
<br><a href="#Quality_Definition">Quality Definition</a>
<br><A href="#Defect_Classification">Classification of Defects</a>
<br><A href="#Release_Policy">Release Policy</a>
<br><A href="#Quality_Tools">Software Quality Tools</a>
<br><A href="#Quality_Processes">Software Quality Processes</a>
<br><A href="#Zoltan_ASC">Zoltan&acute;s implementation of the ASC Software Quality Engineering Practices</a>
</blockquote>
<H3>
<A NAME="Quality_Policy"></A>Quality Policy
</H3>
<p>
Sandia&acute;s ASC Quality Management Council (AQMC) developed and manages the
Quality Assurance Program (QAP) for Sandia&acute;s ASC program. The AQMC chartered
the development of the <I>Sandia National Laboratories Advanced Simulation and Computing
(ASC) Software Quality Plan, Part 1: ASC Software Quality Engineering Practices, Version 2.0</I>
document (SAND 2006-5998) as the practical SQA guidance for projects like Zoltan.
A companion document, <I>Sandia National Laboratories Advanced Simulation and Computing
(ASC) Software Quality Plan, Part 2: Mappings for the ASC Software Quality Practices</I> (SAND 2006-5997),
shows how these practices satisfy corporate policies including CPR001.3.6, Corporate
Software Engineering Excellence, and DOE/NNSA orders 414.1C and QC-1 rev 10.
<p>
The Zoltan project is committed to a program of quality improvement in compliance
with the <I>ASC Software Quality Engineering Practices</I> document. The Zoltan Team Leader is the owner
of the Zoltan quality system. Zoltan developers at Sandia or under contract to Sandia
are required to follow these software development practices. The Zoltan team shall
participate in all reporting processes, audits, and assessments as directed by the AQMC.
<H3><A NAME="Quality_Definition"></A>Quality Definition</H3>
<p>
QC-1 rev 10 defines quality as &quot;the degree to which customer requirements are met.&quot;
<p>
The Zoltan project accepts the following definition of quality:
&quot;the totality of characteristics of a product or service that bear
on its ability to satisfy stated or implied needs.&quot; This is Juran&acute;s
&quot;fitness for use&quot; definition of quality (ANSI/ASQC A8402-1994.)
This superior definition of quality fully satisfies the QC-1 rev 10 definition.
This definition is also more useful in a research environment where the requirements are
derived from a research proposal rather than directly from customers and end users.
<H3><A NAME="Defect_Classification"></A>Classification of Defects</H3>
The Zoltan project accepts the following system of classification of
defects:
<BLOCKQUOTE>
<b>Critical:</b> A defect that could lead to loss of life,
significant environmental damage, or substantial financial loss.
<br><b>Major:</b> A non critical defect that significantly
impacts Zoltan's fitness for use.
<br><b>Minor:</b> A (non critical, non major) defect that
reasonably impacts Zoltan's fitness for use.
<br><b>Incidental:</b> Any other defect which does not
reasonably reduce Zoltan's fitness for use.
</BLOCKQUOTE>
<p>
<H3><A NAME="Release_Policy"></A>Release Policy</H3>
<p>
Only the Zoltan team leader may authorize (certify) a release.
The Zoltan team leader shall not release software with
any known critical or major defects.
User registration shall allow the Zoltan team to
notify all Sandia and ASC users and to recall their
defective software if a critical or major defect
is discovered after release.
The Zoltan team leader may determine that it is
acceptable to release software with known minor or incidental defects.
<p>
<H3><A NAME="Quality_Tools"></A>Software Quality Tools</H3>
<p>
Because of the small scale of the Zoltan Project, only a few, simple tools
are required for use by Zoltan developers:
<BLOCKQUOTE>
<b>CVS:</b> maintains code, documentation, meeting
notes, emails, and QA program artifacts;
<br><b>Purify, PureCoverage, Quantify (Rational), Valgrind, gdb:</b>
for dynamic code testing, coverage measurements, and performance analysis;
<br><b>Bugzilla:</b> tracks bugs, requests for changes,
and enhancements;
<br><b>Mailman:</b> creates email lists to automatically
notify users by area(s) of interest;
<br><b>Makefiles:</b> ensures proper compilation and linking
for all supported platforms; and
<br><b>Zoltan Test Script:</b> runs
integration, regression, release and acceptance testing.
</BLOCKQUOTE>
<H3><A NAME="Quality_Processes"></A>Software Quality Processes</H3>
<p>
<b>Bug Reporting, Issue Tracking, Enhancement Requests:</b> All of these
items are now directly entered into Bugzilla by developers and users.
This &quot;process&quot; is built into the tool. Detailed instructions
for using Bugzilla are found on the Zoltan web page. Bugzilla also
provides query and report features for tracking the status of entered items;.
<p>
A process is defined as a sequence of steps performed for a given
purpose (IEEE Std. 610.12.) Zoltan&acute;s other processes are defined as
checklists because checklists are one of the seven fundamental quality tools.
These checklists are also the primary artifact created when following a process.
Currently the following processes are defined:
<BLOCKQUOTE>
<b>Development:</b> (not currently used) defines the software development
process including
requirements, design, implementation, testing, reviews, and approvals;
<br><b>Release:</b> defines the release process including testing requirements
and creation of the release product;
<br><b>Request:</b> defines the process of
capturing user requests for new features;
<br>&nbsp;&nbsp;Note: this process is now obsolete. Request processes in progress
may continue until complete but new requests should use Bugzilla;
<br><b>Requirement:</b> the process of capturing user comments that
may become requirements after review and approval;
<br>&nbsp;&nbsp;Note: this process is now obsolete. Requirement processes in progress
may continue until complete but new requirements should use Bugzilla;
<br><b>Review:</b> defines the materials reviewed prior to acceptance
for Zoltan release;
<br>&nbsp;&nbsp; Note: Developers are encouraged to use Bugzilla to enter the
specific review process rather than use the Review checklist. At this time this
is an trial effort and either method may be used.
<br><b>Third Party Software:</b>defines the steps required to obtain, manage,
use, and test for software created outside of Zoltan and the ASC program; and
<br><b>Training:</b> defines the material a new developer must read, required
skills to demonstrate and computer accounts that must be obtained.
</BLOCKQUOTE>
<p>
Zoltan's software quality process checklists define how work may be performed,
including process ownership, authorization to perform, activities and their
sequence (when sequencing is required), process instructions, metrics, and
identification of who performed each activity.
<p>
The only allowed source for process checklists is Zoltan's CVS repository
in the SQA_templates directory (under Zoltan_Internal.) A Zoltan developer
initiates a process by obtaining the current CVS version of the process, renaming
it, and committing the renamed process checklist back into CVS in an appropriate
directory on the same day. The process may continue under this committed version
even if its original process is later superseded unless specifically requested by
the Team Leader. After one or more activities are completed, the process
checklist is updated to reflect the results and committed back to CVS (with
appropriate comments.) A process is completed when all required activities
are completed including reviews and approvals (as necessary), and committed to CVS.
The final CVS comment should indicate that the process is complete.
<p>
<H3><A NAME="Zoltan_ASC"></A>
Zoltan&acute;s implementation of the <I>ASC Software Quality Engineering Practices</I></H3>
<p>
The following is brief description <b> for Zoltan developers</b> about the Zoltan
project&acute;s implementation of the <I>ASC Software Quality Engineering Practices</I> (SAND 2006-5998):
<p>
<b>PR1. Document and maintain a strategic plan.</b><br>
The Zoltan web page has a direct hyperlink to the Zoltan Project Description
defining its mission and philosophy. The Zoltan project has a strong association
with the Trilinos project to share in the development of common software
engineering practices and sharing of appropriate tools and experience.
<p>
<b>PR2. Perform a risk-based assessment, determine level of formality
and applicable practices, and obtain approvals.</b><br>
The Zoltan project has an approved level of formality (medium) for its
deliverable software. Its biggest technical risk results from providing
parallel solutions to NP hard partitioning problems. Technical risks are
mitigated by collaborations within Sandia and internationally. The most
significant non-technical risk is the conflicting priorities of Zoltan
developers working on many other projects simultaneously.
<p>
<b>PR3. Document lifecycle processes and their interdependencies, and
obtain approvals.</b><br>
The Zoltan project follows the <I>Trilinos Software Lifecycle Model</I>
(SAND 2006-6929). It also follows the ANSI/ASQ Z1.13-1999 standard
<I>Quality Guidelines for Research</I> which is compatible with the research
phase in the Trilinos Lifecycle model.
<p>
<b>PR4. Define, collect, and monitor appropriate process metrics. </b><br>
The Zoltan project is committed to comply fully with the new and evolving
AQMC requirements for collecting and reporting &quot;defect&quot; metrics.
Other metrics determined by Zoltan&acute;s continual process improvement process
(<b>PR 5</B>) will be implemented.
<p>
<b>PR5. Periodically evaluate quality problems and implement process
improvements.</b><br>
The Zoltan project has built the Deming/Shewhart process improvement
cycle PDCA (Plan, Do, Check, Act) into all of its process checklists. This is
the most effective process improvement technique known. It is recommended
by ISO 9001:2000.
<p>
<b>PR6. Identify stakeholders and other requirements sources.</b><br>
The Zoltan project&acute;s primary stakeholders are the ASC applications using
Zoltan including SIERRA, ACME, ALEGRA/NEVADA, XYCE, and Trilinos.
<p>
<b>PR7. Gather and manage stakeholders&acute; expectations and requirements.</b><br>
The Zoltan project&acute;s primary input from ASC applications&acute; expectations and
requirements are via their communication of Zoltan&acute;s role in meeting their
ASC milestones. Since Zoltan is an &quot;enabling technology,&quot; these requirements
are broadly stated performance improvement needs. The Zoltan team actively anticipates
and develops load balancing software for the future needs of the Sandia research community
before they actually become formal requirements.
<p>
<b>PR8. Derive, negotiate, manage, and trace requirements.</b><br>
Zoltan project requirements normally derive from its funded research proposals
which state research goals. This is a normal procedure in a research
environment (see ANSI/ASQ Z1.13-1999). Periodic and final reports document
the success in meeting these research goals.
<p>
<b>PR9. Identify and analyze risk events.</b><br>
All Zoltan developers should report any new or changed risks via the zoltan-dev
email target for evaluation by the Team Lead.
<p>
<b>PR10. Define, monitor, and implement the risk response.</b><br>
The Zoltan team will create a corrective action plan whenever any condition
threatens to adversely impact the Zoltan project resources or schedule.
<p>
<b>PR11. Create and manage the project plan.</b><br>
ANSI/ASQ Z1.13-1999 states that the research proposal is equivalent to a
project plan in a research environment. The Team Leader assigns responsibilities,
deliverables, resources, and schedules in order to manage the project.
<p>
<b>PR12. Track project performance versus project plan and implement
needed (corrective) actions.</b><br>
The Team Leader periodically tracks responsibilities, deliverables, resources,
and schedules in order to manage the project.
<p>
<b>PR13. Communicate and review design.</b><br>
The Zoltan architecture is fully documented in the Zoltan Developer&acute;s Guide.
New features are originally documented and reviewed in team discussions to
the zoltan-dev email target. Prior to release, the design documentation is
finalized in both the Zoltan Developer&acute;s Guide and the Zoltan User&acute;s Guide.
<p>
<b>PR14. Create required software and product documentation.</b><br>
Developers will follow the Zoltan Development Process Checklist.
<p>
<b>PR15. Identify and track third party software products and follow
applicable agreements.</b><br>
Developers will follow the Zoltan Third Party Software Process Checklist.
<p>
<b>PR16. Identify, accept ownership, and manage the assimilation of other
software products.</b><br>
Not applicable since Zoltan does not &quot;assimilate&quot; third party software.
<p>
<b>PR17. Perform version control of identified software product artifacts.</b><br>
All software and process artifact are under maintained CVS as early as reasonable
after their creation.
<p>
<b>PR18. Record and track issues associated with the software product.</b><br>
Developers will use Bugzilla to record and track issues.
<p>
<b>PR19. Ensure backup and disaster recovery of software product artifacts.</b><br>
Nightly backups, periodic offsite backups, and disaster recovery are services
provided by the CSRI computer support staff. Disaster recovery has been successfully
performed from real problems.
<p>
<b>PR20. Plan and generate the release package.</b><br>
Developers will follow the Zoltan Release Process Checklist.
<p>
<b>PR21. Certify that the software product (code and its related artifacts) is
ready for release and distribution.</b><br>
The Zoltan Team Leader will certify any version of Zoltan for release via an
email to zoltan-dev target.
<p>
<b>PR22. Distribute release to customers.</b><br>
Zoltan files are released via a download from the Zoltan web site. The Zoltan
Team Leader will make the download available after certification. (Research
versions of the Zoltan software are directly available to collaborators for
development.)
<p>
<b>PR23. Define and implement a customer support plan.</b><br>
(See <b>PR 6</b> for a list of ASC stakeholders.) The Zoltan team provides one-on-one
training whenever requested and quickly responds to any user complaint.
<p>
<b>PR24. Implement the training identified in the customer support plan.</b><br>
See <b>PR 23</b> above. If additional training is ever requested, the Zoltan project
will piggy back on the annual Trilinos Users Group meeting with a training
session on using Zoltan.
<p>
<b>PR25. Evaluate customer feedback to determine customer satisfaction.</b><br>
<p>
<p>
<b>PR 26 Develop and maintain a software verification plan.</b><br>
Developers are expected to create new tests for the Zoltan test suite when
new features are added to Zoltan.
<p>
Currently, a new test framework based on FAST/EXACT is being implemented.
Documentation about this test framework is under preparation. A process
checklist will be developed around the steps required to add new tests to
the suite and to run the suite.
<p>
<b>PR27. Conduct tests to demonstrate that acceptance criteria are met and to
ensure that previously tested capabilities continue to perform as expected.</b><br>
This practice is a subset of the Zoltan Release Process Checklist.
<p>
<b>PR28. Conduct independent technical reviews to evaluate adequacy with respect
to requirements.</b><br>
Developers will follow the Zoltan Review Process Checklist. ANSI/ASQ Z1.13-1999
states that the peer reviewed publications and conference presentations are a normal
form of technical review in the research environment.
<p>
<b>PR29. Determine project team training needed to fulfill assigned roles
and responsibilities.</b><br>
New developers will follow the Zoltan Training Process for new team members.
<p>
<b>PR30. Track training undertaken by project teams.</b><br>
Zoltan developers are encouraged to participate in the annual Trilios Users Group
(TUG) meeting which provides sessions for SQA/SQE training to developers.
Attendance records are kept for this event and for any Zoltan team meetings that
provide training. Sandia provides many other opportunities for training including
formal courses and periodic internal software developers conferences. External
conferences (e.g., IPDPS and SIAM) are counted as technical training.
<p>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A> | <A HREF="dev_dist.html">Next:
Zoltan Distribution</A> | <A HREF="dev_intro_coding.html">Previous:
Coding Principles in Zoltan</A>
| <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

78
thirdParty/Zoltan/docs/dev_html/dev_lb.html vendored Normal file
View File

@ -0,0 +1,78 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: Load-Balancing</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_lb_interface.html">Next</a>&nbsp; |&nbsp; <a href="dev_dist_compile.html">Previous</a></i></b></div>
<H2>
<A NAME="interface"></A>Zoltan Interface and Data Structures</H2>
The interface functions, data types and data structures
for the Zoltan library are described in the following sections:
<BLOCKQUOTE><A HREF="dev_lb_interface.html">Interface Functions</A>&nbsp;
(files defining the interface)
<BR><A HREF="dev_lb_types.html">ID Data Types</A> (descriptions
of data types used for global and local identifiers)
<BR><A HREF="dev_lb_structs.html">Data Structures</A> (Zoltan data structures
for storing information registered by an application)
<BR>&nbsp;</BLOCKQUOTE>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_lb_interface.html">Next:&nbsp;
Interface Functions</A>&nbsp; |&nbsp; <A HREF="dev_dist_compile.html">Previous:&nbsp;
Compilation</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

104
thirdParty/Zoltan/docs/dev_html/dev_lb_interface.html vendored Normal file
View File

@ -0,0 +1,104 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: Load-Balancing Interface</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_lb_types.html">Next</a>&nbsp; |&nbsp; <a href="dev_lb.html">Previous</a></i></b></div>
<H2>
<A NAME="interface_fns"></A>Interface Functions</H2>
The interface to the Zoltan library is defined in the file
<I>include/zoltan.h</I>. This file should be included in application programs
that use Zoltan. It is also included in <I>zz/zz_const.h</I>,
which should be included by most Zoltan files to provide
access to the Zoltan data structures described below.
<P>In <I>include/zoltan.h</I>, the enumerated type <B>ZOLTAN_FN_TYPE</B> defines
the application query function types (e.g., <B><A HREF="../ug_html/ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN_TYPE</A></B>
and <B><A HREF="../ug_html/ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN_TYPE</A></B>).
The interface query routines (e.g., <B><A HREF="../ug_html/ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</A></B>
and <B><A HREF="../ug_html/ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</A></B>)
and their argument lists are defined as C type definitions (typedef). These
type definitions are used by the application developer to implement the
query functions needed for the application to use Zoltan.
<P>Prototypes for the Zoltan interface functions
(e.g., <B><A HREF="../ug_html/ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</A></B>
and <B><A HREF="../ug_html/ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</A></B>)
are also included in <I>include/zoltan.h</I>. Interface functions are called
by the application to register functions, select a load-balancing method,
invoke load balancing and migrate data.
<P>The interface to the C++ version of the Zoltan library is in the file
<I>include/zoltan_cpp.h</I>. This file defines the <B>Zoltan</B> class,
representing a <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>
data structure and the functions which
operate upon it. The conventions used to wrap C library functions as
C++ library functions are described in the chapter
<B><a href="dev_cpp.html">C++ Interface</a></B>.
A C++ program that uses Zoltan includes <I>include/zoltan_cpp.h</I>
instead of <I>include/zoltan.h</I>.
<P>For more detailed information on Zoltan's query and interface functions,
please see the <A HREF="../ug_html/ug.html">Zoltan User's Guide</A>.
<P>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_lb_types.html">Next:&nbsp;
ID Data Types</A>&nbsp; |&nbsp; <A HREF="dev_lb.html">Previous:&nbsp;
Zoltan Interface and Data Structures</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

861
thirdParty/Zoltan/docs/dev_html/dev_lb_structs.html vendored Normal file
View File

@ -0,0 +1,861 @@
<!-------- @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: Load Balancing Data Structures</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_services.html">Next</a>&nbsp; |&nbsp; <a href="dev_lb_types.html">Previous</a></i></b></div>
<h2>
<a NAME="interface_structs"></a>Data Structures</h2>
The <b>Zoltan_Struct</b> data structure is the main data structure for interfacing
between Zoltan and the application. The application
creates an <b>Zoltan_Struct</b> data structure through a call to <b><a href="../ug_html/ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>.
Fields of the data structure are then set through calls from the application
to interface routines such as <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
and <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>.
The fields of the <b>Zoltan_Struct</b> data structure are listed and described
in the <a href="#Zoltan_Struct">table</a> below. See the <a href="../ug_html/ug.html">Zoltan
User's Guide</a> for descriptions of the function types used in the <b>Zoltan_Struct</b>.
<p>A <b>Zoltan_Struct</b> data structure <i>zz</i> is passed from the application
to Zoltan in the call to <b><a href="../ug_html/ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>.
This data structure is passed to the individual load-balancing routines.
The <i>zz->LB.Data_Structure</i> pointer field should point to the main data
structures of the particular load-balancing algorithm so that the data
structures may be preserved for future calls to <b><a href="../ug_html/ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
and so that separate instances of the same load-balancing algorithm (with
different <b>Zoltan_Struct</b> structures) can be used by the application.
<br>&nbsp;
<center><table BORDER WIDTH="90%" NOSAVE >
<tr>
<th><a NAME="Zoltan_Struct"></a>Fields of Zoltan_Struct</th>
<th>Description</th>
</tr>
<tr>
<td VALIGN=TOP>MPI_Comm <i>Communicator</i></td>
<td>The MPI communicator to be used by the Zoltan structure; set
by
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Proc</i></td>
<td>The rank of the processor within <i>Communicator</i>; set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Num_Proc</i></td>
<td>The number of processors in <i>Communicator</i>; set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Num_GID</i></td>
<td>The number of array entries used to represent a
<a href="dev_lb_types.html">global ID</a>.
Set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>.
</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Num_LID</i></td>
<td>The number of array entries used to represent a
<a href="dev_lb_types.html">local ID</a>.
Set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>.
</td>
</tr>
<tr>
<td VALIGN=TOP>int <i><a href="../ug_html/ug_param.html#Debug Levels in Zoltan">Debug_Level</a></i></td>
<td>A flag indicating the amount of debugging information that should be
printed by Zoltan.</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Fortran</i></td>
<td>A flag indicating whether or not the structure was created by a call
from Fortran.</td>
</tr>
<tr>
<td VALIGN=TOP>PARAM_LIST *<i> Params</i></td>
<td>A linked list of string pairs. The first item in each pair is the name
of a modifiable parameter. The second string is the new value the parameter
should adopt. These string pairs are read upon invocation of a Zoltan
algorithm and the appropriate parameter changes are made. This design allows
for different Zoltan structures to have different parameter settings.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>int <i>Deterministic</i></td>
<td>Flag indicating whether algorithms used should be forced to be deterministic;
used to obtain completely reproducible results.&nbsp; Set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_param.html#DETERMINISTIC">DETERMINISTIC</a>.</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Obj_Weight_Dim</i></td>
<td>Number of weights per object.
&nbsp; Set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_param.html#OBJ_WEIGHT_DIM">OBJ_WEIGHT_DIM</a>.</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Edge_Weight_Dim</i></td>
<td>For graph algorithms, number of weights per edge.
Set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_param.html#EDGE_WEIGHT_DIM">EDGE_WEIGHT_DIM</a>.</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Timer</i></td>
<td> Timer type that is currently active.
Set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_param.html#TIMER">TIMER</a>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_EDGES">ZOLTAN_NUM_EDGES_FN</a>
*<i> Get_Num_Edges</i></td>
<td>A pointer to an application-registered function that returns the number
of edges associated with a given object. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Edges_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Num_Edges_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Num_Edges</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Edges_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a>
*<i> Get_Edge_List</i></td>
<td>A pointer to an application-registered function that returns a given
object's neighbors along its edges. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Edge_List_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Edge_List_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Edge_List</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Edge_List_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a>
*<i> Get_Num_Geom</i></td>
<td>A pointer to an application-registered function that returns the number
of geometry values needed to describe the positions of objects. Set in
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Geom_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Num_Geom_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Num_Geom</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Geom_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a>
*<i> Get_Geom</i></td>
<td>A pointer to an application-registered function that returns a given
object's geometry information (e.g., coordinates). Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Geom_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Geom_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Geom</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Geom_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a>
*<i> Get_Num_Obj</i></td>
<td>A pointer to an application-registered function that returns the number
of objects assigned to the processor before load balancing. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Num_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Num_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a>
*<i> Get_Obj_List</i></td>
<td>A pointer to an application-registered function that returns arrays
of objects assigned to the processor before load balancing. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Obj_List_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Obj_List_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Obj_List</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Obj_List_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_FIRST_OBJ_FN">ZOLTAN_FIRST_OBJ_FN</a>
*<i> Get_First_Obj</i></td>
<td>A pointer to an application-registered function that returns the first
object assigned to the processor before load balancing. Used with <i>Get_Next_Obj</i>
as an iterator over all objects. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_First_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_First_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_First_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_First_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_NEXT_OBJ_FN">ZOLTAN_NEXT_OBJ_FN</a>
*<i> Get_Next_Obj</i></td>
<td>A pointer to an application-registered function that, given an object
assigned to the processor, returns the next object assigned to the processor
before load balancing. Used with <i>Get_First_Obj</i> as an iterator over
all objects. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Next_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Next_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Next_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Next_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_BORDER_OBJ_FN">ZOLTAN_NUM_BORDER_OBJ_FN</a>
*<i> Get_Num_Border_Obj</i></td>
<td>A pointer to an application-registered function that returns the number
of objects sharing a subdomain border with a given processor. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Border_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Num_Border_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Num_Border_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Border_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_BORDER_OBJ_LIST_FN">ZOLTAN_BORDER_OBJ_LIST_FN</a>
*<i> Get_Border_Obj_List</i></td>
<td>A pointer to an application-registered function that returns arrays
of objects that share a subdomain border with a given processor. Set in
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Border_Obj_List_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Border_Obj_List_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Border_Obj_List</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Border_Obj_List_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_FIRST_BORDER_OBJ_FN">ZOLTAN_FIRST_BORDER_OBJ_FN</a>
*<i> Get_First_Border_Obj</i></td>
<td>A pointer to an application-registered function that returns the first
object sharing a subdomain border with a given processor. Used with <i>Get_Next_Border_Obj</i>
as an iterator over objects along borders. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_First_Border_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_First_Border_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_First_Border_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_First_Border_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_NEXT_BORDER_OBJ_FN">ZOLTAN_NEXT_BORDER_OBJ_FN</a>
*<i> Get_Next_Border_Obj</i></td>
<td>A pointer to an application-registered function that, given an object,
returns the next object sharing a subdomain border with a given processor.
Used with <i>Get_First_Border_Obj</i> as an iterator over objects along
borders. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Next_Border_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Next_Border_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Next_Border_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Next_Border_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_COARSE_OBJ_FN">ZOLTAN_NUM_COARSE_OBJ_FN</a>
*<i> Get_Num_Coarse_Obj</i></td>
<td>A pointer to an application-registered function that returns the number
of objects in the initial coarse grid. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Coarse_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Num_Coarse_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Num_Coarse_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Coarse_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_COARSE_OBJ_LIST_FN">ZOLTAN_COARSE_OBJ_LIST_FN</a>
*<i> Get_Coarse_Obj_List</i></td>
<td>A pointer to an application-registered function that returns arrays
of objects in the initial coarse grid. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Coarse_Obj_List_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Coarse_Obj_List_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Coarse_Obj_List</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Coarse_Obj_List_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_FIRST_COARSE_OBJ_FN">ZOLTAN_FIRST_COARSE_OBJ_FN</a>
*<i> Get_First_Coarse_Obj</i></td>
<td>A pointer to an application-registered function that returns the first
object of the initial coarse grid. Used with <i>Get_Next_Coarse_Obj</i>
as an iterator over all objects in the coarse grid. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_First_Coarse_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_First_Coarse_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_First_Coarse_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_First_Coarse_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_NEXT_COARSE_OBJ_FN">ZOLTAN_NEXT_COARSE_OBJ_FN</a>
*<i> Get_Next_Coarse_Obj</i></td>
<td>A pointer to an application-registered function that, given an object
in the initial coarse grid, returns the next object in the coarse grid.
Used with <i>Get_First_Coarse_Obj</i> as an iterator over all objects in
the coarse grid. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Next_Coarse_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Next_Coarse_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Next_Coarse_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Next_Coarse_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_CHILD_FN">ZOLTAN_NUM_CHILD_FN</a>
*<i> Get_Num_Child</i></td>
<td>A pointer to an application-registered function that returns the number
of refinement children of an object. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Child_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Num_Child_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Num_Child</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Num_Child_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_CHILD_LIST_FN">ZOLTAN_CHILD_LIST_FN</a>
*<i> Get_Child_List</i></td>
<td>A pointer to an application-registered function that returns arrays
of objects that are refinement children of a given object. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Child_List_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Child_List_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Child_List</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Child_List_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_lb.html#ZOLTAN_CHILD_WEIGHT_FN">ZOLTAN_CHILD_WEIGHT_FN</a>
*<i> Get_Child_Weight</i></td>
<td>A pointer to an application-registered function that returns the weight
of an object. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Child_Weight_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Child_Weight_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Child_Weight</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Child_Weight_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN</a>
*<i> Get_Obj_Size</i></td>
<td>A pointer to an application-registered function that returns the size
(in bytes) of data objects to be migrated. Called by <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>.&nbsp;
Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Obj_Size_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Get_Obj_Size_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Get_Obj_Size</i>.&nbsp; Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Obj_Size_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN</a>
*<i> Pack_Obj</i></td>
<td>A pointer to an application-registered function that packs all data
for a given object into a communication buffer provided by the migration
tools in preparation for data-migration communication. Called by <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>
for each object to be exported.&nbsp; Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Pack_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Pack_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Pack_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Pack_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN</a>
*<i> Unpack_Obj</i></td>
<td>A pointer to an application-registered function that unpacks all data
for a given object from a communication buffer after the communication
for data migration is completed. Called by <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>
for each imported object.&nbsp; Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Unpack_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Unpack_Obj_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Unpack_Obj</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Unpack_Obj_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>ZOLTAN_LB <i>LB</i></td>
<td>A structure with data used by the load-balancing tools. See the <a href="#LB_Fields">table</a>
below.</td>
</tr>
<tr>
<td VALIGN=TOP>ZOLTAN_MIGRATE <i>Migrate</i></td>
<td>A structure with data used by the migration tools. See the <a href="#Migrate_Fields">table</a>
below.</td>
</tr>
<caption ALIGN=BOTTOM><i>Fields of the </i><b>Zoltan_Struct</b><i> data structure.</i></caption>
</table></center>
<p>Each <b>Zoltan_Struct</b> data structure has a <b>ZOLTAN_LB</b> sub-structure.
The <b>ZOLTAN_LB</b> structure contains data used by the load-balancing tools,
including pointers to specific load-balancing methods and load-balancing data
structures.
The fields of the <b>ZOLTAN_LB</b> structure are listed and described
in in the following <a href="#LB_Fields">table</a>.
<br>&nbsp;
<center><table BORDER WIDTH="90%" NOSAVE >
<tr>
<th><a NAME="LB_Fields"></a>Fields of ZOLTAN_LB</th>
<th>Description</th>
</tr>
<tr>
<td VALIGN=TOP>void *<i> Data_Structure</i></td>
<td>The <a href="dev_add_struct.html">data structure</a> used by the selected load-balancing algorithm; this
pointer is cast by the algorithm to the appropriate data type.</td>
</tr>
<tr>
<td VALIGN=TOP>double <i>Imbalance_Tol</i></td>
<td>The degree of load balance which is considered acceptable.
Set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_alg.html#IMBALANCE_TOL">IMBALANCE_TOL</a>.</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Num_Global_Parts</i></td>
<td>
The total number of parts to be generated.
Set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_alg.html#NUM_GLOBAL_PARTS">NUM_GLOBAL_PARTS</a> or through
summation of
<a href="../ug_html/ug_alg.html#NUM_LOCAL_PARTS">NUM_LOCAL_PARTS</a>
parameters.
</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Num_Local_Parts</i></td>
<td>
The number of parts to be generated on this processor.
Set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_alg.html#NUM_LOCAL_PARTS">NUM_LOCAL_PARTS</a> or (roughly) through
division of the
<a href="../ug_html/ug_alg.html#NUM_GLOBAL_PARTS">NUM_GLOBAL_PARTS</a>
parameter by the number of processors.
</td>
</tr>
<tr>
<td VALIGN=TOP>int <i>Return_Lists</i></td>
<td>A flag indicating whether the application wants import and/or export
lists returned by <a href="../ug_html/ug_interface_lb.html#Zoltan_LB_Partition"><b>Zoltan_LB_Partition</b></a>.
Set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>.</td>
</tr>
<tr>
<td VALIGN=TOP>ZOLTAN_LB_METHOD <i>Method</i></td>
<td>An enumerated type designating which load-balancing algorithm should
be used with this Zoltan structure;
set via a call to
<b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_alg.html#LB_METHOD">LB_METHOD</a>.
</td>
</tr>
<tr>
<td VALIGN=TOP>LB_FN *<i> LB_Fn</i></td>
<td>A pointer to the load-balancing function specified by <i>Method</i>.
</td>
</tr>
<tr>
<td VALIGN=TOP>ZOLTAN_LB_FREE_DATA_FN <i>*Free_Structure</i></td>
<td> Pointer to a function that frees the Data_Structure memory.
</td>
</tr>
<tr>
<td VALIGN=TOP>ZOLTAN_LB_POINT_ASSIGN_FN <i>*Point_Assign</i></td>
<td> Pointer to the function that performs
<a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Point_Assign">Zoltan_LB_Point_Assign</a> for the particular load-balancing method.
</td>
</tr>
<td VALIGN=TOP>ZOLTAN_LB_BOX_ASSIGN_FN <i>*Box_Assign</i></td>
<td> Pointer to the function that performs
<a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Box_Assign">Zoltan_LB_Box_Assign</a> for the particular load-balancing method.
</td>
</tr>
<caption ALIGN=BOTTOM><i>Fields of the </i><b>ZOLTAN_LB</b><i> data structure.</i></caption>
</table></center>
<p>Each <b>Zoltan_Struct</b> data structure has a <b>ZOLTAN_MIGRATE</b> sub-structure.
The <b>ZOLTAN_MIGRATE</b> structure contains data used by the migration tools,
including pointers to pre- and post-processing routines. These pointers
are set through the interface routine <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
and are used in <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>.
The fields of the <b>ZOLTAN_MIGRATE</b> structure are listed and described
in in the following <a href="#Migrate_Fields">table</a>.
<br>&nbsp;
<center><table BORDER WIDTH="90%" NOSAVE >
<tr>
<th><a NAME="Migrate_Fields"></a>Fields of ZOLTAN_MIGRATE</th>
<th>Description</th>
</tr>
<tr>
<td VALIGN=TOP>int <i>Auto_Migrate</i></td>
<td>A flag indicating whether Zoltan should perform
auto-migration for the application. If true, Zoltan
calls <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>
to move objects to their new processors; if false, data migration is left
to the user. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
for <a href="../ug_html/ug_alg.html#AUTO_MIGRATE">AUTO_MIGRATE</a>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN">ZOLTAN_PRE_MIGRATE_PP_FN</a>
*<i> Pre_Migrate_PP</i></td>
<td>A pointer to an application-registered function that performs pre-processing
for data migration. The function is called by <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>
before data migration is performed. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Pre_Migrate_PP_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Pre_Migrate_PP_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Pre_Migrate_PP</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Pre_Migrate_PP_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN">ZOLTAN_MID_MIGRATE_PP_FN</a>
*<i> Mid_Migrate_PP</i></td>
<td>A pointer to an application-registered function that performs processing
between the packing and unpacking operations in <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>.
Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Mid_Migrate_PP_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Mid_Migrate_PP_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Mid_Migrate_PP</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Mid_Migrate_PP_Fn</a></b>.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE><a href="../ug_html/ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN">ZOLTAN_POST_MIGRATE_PP_FN</a>
*<i>Post_Migrate_PP</i></td>
<td>A pointer to an application-registered function that performs post-processing
for data migration. The function is called by <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>
after data migration is performed. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Post_Migrate_PP_Fn</a></b>.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>void *<i>Post_Migrate_PP_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Post_Migrate_PP</i>.&nbsp; Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Post_Migrate_PP_Fn</a></b>.&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_mig.html#ZOLTAN_PRE_MIGRATE_FN">ZOLTAN_PRE_MIGRATE_FN</a>
*<i> Pre_Migrate</i></td>
<td>A pointer to an application-registered function that performs pre-processing
for data migration. The function is called by <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Help_Migrate">Zoltan_Help_Migrate</a></b>
before data migration is performed. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Pre_Migrate_Fn</a></b>.
Maintained for backward compatibility with Zoltan v1.3 interface.
</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Pre_Migrate_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Pre_Migrate</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Pre_Migrate_Fn</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><a href="../ug_html/ug_query_mig.html#ZOLTAN_MID_MIGRATE_FN">ZOLTAN_MID_MIGRATE_FN</a>
*<i> Mid_Migrate</i></td>
<td>A pointer to an application-registered function that performs processing
between the packing and unpacking operations in <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Help_Migrate">Zoltan_Help_Migrate</a></b>.
Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Mid_Migrate_Fn</a></b>.
Maintained for backward compatibility with Zoltan v1.3 interface.
</td>
</tr>
<tr>
<td VALIGN=TOP>void <i>*Mid_Migrate_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Mid_Migrate</i>. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Mid_Migrate_Fn</a></b>.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE><a href="../ug_html/ug_query_mig.html#ZOLTAN_POST_MIGRATE_FN">ZOLTAN_POST_MIGRATE_FN</a>
*<i>Post_Migrate</i></td>
<td>A pointer to an application-registered function that performs post-processing
for data migration. The function is called by <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Help_Migrate">Zoltan_Help_Migrate</a></b>
after data migration is performed. Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Post_Migrate_Fn</a></b>.
Maintained for backward compatibility with Zoltan v1.3 interface.
</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>void *<i>Post_Migrate_Data</i></td>
<td>A pointer to data provided by the user that will be passed to the function
pointed to by <i>Post_Migrate</i>.&nbsp; Set in <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_Post_Migrate_Fn</a></b>.&nbsp;</td>
</tr>
<caption ALIGN=BOTTOM><i>Fields of the </i><b>ZOLTAN_MIGRATE</b><i> data structure.</i></caption>
</table></center>
<p>For each pointer to an application registered function in the
<b>Zoltan_Struct</b>
and <b>ZOLTAN_MIGRATE</b> data structures there is also a pointer to a Fortran
application registered function, of the form ZOLTAN_FUNCNAME_FORT_FN *<i>Get_Funcname_Fort</i>.
These are for use within the Fortran interface. The Zoltan routines
should invoke the usual application registered function regardless of whether
the Zoltan structure was created from C or Fortran.
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_services.html">Next:&nbsp;
Services</a>&nbsp; |&nbsp; <a href="dev_lb_types.html">Previous:&nbsp;
ID Data Types</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

249
thirdParty/Zoltan/docs/dev_html/dev_lb_types.html vendored Normal file
View File

@ -0,0 +1,249 @@
<!-------- @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: Data Types</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_lb_structs.html">Next</a>&nbsp; |&nbsp; <a href="dev_lb_interface.html">Previous</a></i></b></div>
<h2>
<a NAME="interface_types"></a>ID Data Types</h2>
Within Zoltan, objects are identified by a global
identification (ID) value provided by the application. This global ID must
be unique across all processors. The application may also provide a local
ID value that it can use for faster location of objects within its own
data structure. For example, local array indices to objects' data may be
provided as the local IDs; these indices can then be used to directly access
data in the query functions. Zoltan does not use these
local IDs, but since it must pass them to the application in the interface
query functions, it must store them with the objects' data.&nbsp; ID data
types and macros for manipulating IDs are described below.
<blockquote><a href="#ID arrays">IDs and Arrays of IDs</a>
<br><a href="#ID alloc">Allocating IDs</a>
<br><a href="#ID Ops">Common Operations on IDs</a></blockquote>
<h4>
<a NAME="ID arrays"></a>IDs and Arrays of IDs</h4>
Zoltan stores each global and local ID as an array of unsigned integers.
Arrays of IDs are passed to the application as a one-dimensional array
of unsigned integers with size
<i>number_of_IDs</i> * <i>number_of_entries_per_ID</i>.
A type definition <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
(in <i>include/zoltan_types.h</i>) points to an ID or array of IDs. The number
of array entries per ID can be set by the application using the <a href="../ug_html/ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and
<a href="../ug_html/ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>
parameters.
<h4>
<a NAME="ID alloc"></a>Allocating IDs</h4>
Macros that simplify the allocation of global and local IDs are described
in the table below. These macros provide consistent, easy-to-use memory
allocation with error checking and, thus, their use is highly recommended.&nbsp;
Each macro returns NULL if either a memory error occurs or the number of
IDs requested is zero.
<br>&nbsp;
<table BORDER WIDTH="100%" NOSAVE >
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_MALLOC_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>);</td>
<td>Allocates and returns a pointer to a single global ID.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_MALLOC_LID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>);</td>
<td>Allocates and returns a pointer to a single local ID.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_MALLOC_GID_ARRAY</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, int <i>n</i>);</td>
<td>Allocates and returns a pointer to an array of <i>n</i> global IDs,
where the index into the array for the <i>i<sup>th</sup></i> global ID
is <i>i</i>*<a href="../ug_html/ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_MALLOC_LID_ARRAY</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, int <i>n</i>);</td>
<td>Allocates and returns a pointer to an array of <i>n</i> local IDs,
where the index into the array for the <i>i<sup>th</sup></i> local ID is
<i>i</i>*<a href="../ug_html/ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_REALLOC_GID_ARRAY</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz,</i> <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>ptr</i>, int <i>n</i>);</td>
<td>Reallocates and returns a pointer to an array of<i> n</i> global IDs,
replacing the current array pointed to by<i> ptr</i>.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<b>ZOLTAN_REALLOC_LID_ARRAY</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz,</i> <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>ptr</i>, int <i>n</i>);</td>
<td>Reallocates and returns a pointer to an array of<i> n</i> local IDs,
replacing the current array pointed to by<i> ptr</i>.</td>
</tr>
</table>
<h4>
<a NAME="ID Ops"></a>Common Operations on IDs</h4>
In addition, macros are defined for common operations on global and local
IDs.&nbsp; These macros include error checking when appropriate and account
for different values of <a href="../ug_html/ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and <a href="../ug_html/ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>.&nbsp;
Use of these macros improves code robustness and simplifies code maintenance;
their use is highly recommended.
<br>&nbsp;
<table BORDER WIDTH="100%" NOSAVE >
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>void<b> ZOLTAN_INIT_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>id</i>);</td>
<td>Initializes all entries of the global ID <i>id</i> to zero; <i>id</i>&nbsp;
must be allocated before calling <b>ZOLTAN_INIT_GID</b>.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>void<b> ZOLTAN_INIT_LID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>id</i>);</td>
<td>Initializes all entries of the local ID <i>id</i> to zero; <i>id</i>&nbsp;
must be allocated before calling <b>ZOLTAN_INIT_LID</b>.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>void<b> ZOLTAN_SET_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>tgt</i>,
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>src</i>);</td>
<td>Copies the global ID <i>src</i> into the global ID <i>tgt</i>.&nbsp;
Both <i>src</i> and <i>tgt</i> must be allocated before calling <b>ZOLTAN_SET_LID</b>.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>void<b> ZOLTAN_SET_LID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>tgt</i>,
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>src</i>);</td>
<td>Copies the local ID <i>src</i> into the local ID <i>tgt</i>.&nbsp;
Both <i>src</i> and <i>tgt</i> must be allocated before calling <b>ZOLTAN_SET_LID</b>.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>int<b> ZOLTAN_EQ_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>a</i>,
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>b</i>);</td>
<td>Returns TRUE if global ID<i> a</i> is equal to global ID <i>b</i>.</td>
</tr>
<!-------------------- KDD COMMENTED OUT WHILE NOT USED IN CODE
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>int<b> ZOLTAN_LT_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>a</i>,
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>b</i>);</td>
<td>Returns TRUE if global ID<i> a</i> is less than global ID <i>b.</i></td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>int<b> ZOLTAN_GT_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>a</i>,
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
<i>b</i>);</td>
<td>Returns TRUE if global ID<i> a</i> is greater than global ID <i>b.</i></td>
</tr>
-------------------->
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>void<b> ZOLTAN_PRINT_GID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>id</i>);</td>
<td>Prints all entries of a single global ID <i>id</i>.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>void<b> ZOLTAN_PRINT_LID</b>(struct <a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a>
*<i>zz</i>, <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>&nbsp;<i>id</i>);</td>
<td NOSAVE>Prints all entries of a single local ID <i>id</i>.</td>
</tr>
</table>
<p>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_lb_structs.html">Next:&nbsp;
Data Structures</a>&nbsp; |&nbsp; <a href="dev_lb_interface.html">Previous:&nbsp;
Interface Functions</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

78
thirdParty/Zoltan/docs/dev_html/dev_mig.html vendored Normal file
View File

@ -0,0 +1,78 @@
<!-------- @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: Migration Tools</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_fortran.html">Next</a>&nbsp; |&nbsp; <a href="dev_add_remap.html">Previous</a></i></b></div>
<h2>
<a NAME="migration_help"></a>Migration Tools</h2>
The migration tools in the Zoltan library perform communication necessary
for data migration in the application. The routine <b><a href="../ug_html/ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>
calls application-registered <a href="../ug_html/ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">packing</a> routines to gather data to be sent
to other processors. It sends the data using the <a href="../ug_html/ug_util_comm.html">unstructured
communication package</a>. It then calls application-registered <a href="../ug_html/ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">unpacking</a>
routines for each imported object to add received data to the processor's
data structures. See the <a href="../ug_html/ug.html">Zoltan User's Guide</a>
for more details on the use of and interface to the migration tools.
<p>In future releases, the migration tools will be updated to use
MPI&nbsp;data types to support heterogeneous computing architectures.
<br>&nbsp;
<p>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_fortran.html">Next:&nbsp;
FORTRAN Interface</a>&nbsp; |&nbsp; <a href="dev_add_remap.html">Previous:&nbsp;
Part Remapping</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

176
thirdParty/Zoltan/docs/dev_html/dev_parmetis.html vendored Normal file
View File

@ -0,0 +1,176 @@
<!-------- @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.6 sun4m) [Netscape]">
<meta name="sandia.approved" content="SAND99-1376">
<meta name="author" content="karen devine, kddevin@sandia.gov">
<title> Zoltan Developer's Guide: ParMETIS/Jostle</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_phg.html">Next</a>&nbsp; |&nbsp; <a href="dev_rib.html">Previous</a></i></b></div>
<h2>
Appendix: <a href="https://www-users.cs.umn.edu/~karypis/metis/parmetis/">ParMETIS</a>
and <a href="https://www.gre.ac.uk/jostle">Jostle</a></h2>
<h3>
Overview of structure (algorithm)</h3>
This part of Zoltan provides an interface to various graph-based load-balancing
algorithms. Currently two libraries are supported: <a href="../ug_html/ug_alg_parmetis.html">ParMETIS
</a>and
<a href="../ug_html/ug_alg_jostle.html">Jostle.</a>
Each of these libraries contain several algorithms.
<h4>
Interface algorithm</h4>
The structure of the code is as follows: Each package
(<a href="https://www-users.cs.umn.edu/~karypis/metis/parmetis/">ParMETIS</a>,
<a href="https://www.gre.ac.uk/jostle">Jostle</a>)
has its own wrapper routine that performs initialization and sets parameters.
The main routine is <b>Zoltan_ParMetis_Jostle,</b> which constructs an appropriate
graph data structure using Zoltan's query functions. After the graph structure
has been constructed, the appropriate library is called and the import/export
list is created and returned.
<p>Please note that <a href="https://www-users.cs.umn.edu/~karypis/metis/parmetis/">ParMETIS</a>
and <a href="https://www.gre.ac.uk/jostle">Jostle</a> are not integral parts
of Zoltan. These libraries must be obtained and installed separately.
(<a href="https://www-users.cs.umn.edu/~karypis/metis/parmetis/">ParMETIS</a>
may be bundled with Zoltan, but it is an independent package developed
at Univ. of Minnesota.) Zoltan merely provides an interface to these libraries.
<p>The most complex task in the interface code is the construction of the
graph data structure. This structure is described in the next section.
The routine uses the Zoltan query functions to get a list of objects and
edges on each processor. Each object has a unique global ID which is mapped
into a unique (global) number between 1 and <i>n</i>, where <i>n</i> is
the total number of objects. The construction of the local (on-processor)
part of the graph is straightforward. When an edge goes between objects
that reside on different processors, global communication is required.
We use Zoltan's unstructured communication library for this. A hash function
(<a href="dev_services_hash.html"><b>Zoltan_Hash</b></a>) is used to efficiently map global IDs to integers.
The graph construction algorithm has parallel complexity
<i>O(max<sub>j</sub> {n<sub>j</sub>+m<sub>j</sub>+p})</i>, where
<i>n<sub>j</sub></i> is the number of objects on processor j,
<i>m<sub>j</sub></i> is the number of edges on processor j, and
<i>p</i> is the number of processors.
<p>One other feature of the interface code should be mentioned.&nbsp; While
Zoltan allows objects and edges to have real (float) weights, both ParMETIS and Jostle
currently require integer weights. Therefore, Zoltan first checks if the
object weights are integers. If not, the weights are automatically scaled
and rounded to integers. The scaling is performed such that the weights
become large integers, subject to the constraint that the sum of (any component
of) the weights is less than a large constant MAX_WGT_SUM &lt; INT_MAX.
The scaled weights are rounded up to the nearest integer to ensure that
nonzero weights never become zero.
Note that for multidimensional weights, each weight component is scaled independently.
(The source code is written such that this scaling is simple to change.)
<p>Currently Zoltan constructs and discards the entire graph structure
every time a graph-based method (ParMETIS or Jostle) is called. Incremental
update of the graph structure may be supported in the future.
<p>The graph construction code in <b>Zoltan_ParMetis_Jostle </b>can also be
used to interface with other graph-based algorithms.
<h4>
Algorithms used in ParMETIS and Jostle libraries</h4>
There are two main types of algorithms used in ParMETIS and Jostle. The
first is multilevel graph partitioning. The main idea is to take a large
graph and&nbsp; construct a sequence of smaller and simpler graphs that
in some sense approximate the original graph. When the graph is sufficiently
small it is partitioned using some other method. This smallest graph and
the corresponding partition is then propagated back through all the levels
to the original graph. A popular local refinement strategy known as Kernighan-Lin
is employed at some or every level.
<p>The second main strategy is diffusion. This method assumes that an initial
partition (balance) is given, and load balance is achieved by repeatedly
moving objects (nodes) from parts (processors) that have too heavy
load to neighboring parts (processors) with too small load.
<p>For further details about the algorithms in a specific library, please
refer to the documentation that is distributed with that library.
<h3>
Data structures</h3>
We use the ParMETIS parallel graph structure. This is implemented using
5 arrays:
<ol>
<li>
<i>vtxdist</i>: gives the distribution of the objects (vertices) to processors</li>
<li>
<i>xadj</i>: indices (pointers) to the <i>adjncy</i> array</li>
<li>
<i>adjncy</i>: neighbor lists</li>
<li>
<i>adjwgt</i>: edge weights</li>
<li>
<i>vwgt</i>: vertex (object) weights</li>
</ol>
The <i>vtxdist</i> array is duplicated on all processors, while the other
arrays are local.
<br>For more details, see the ParMETIS User's Guide.
<h3>
Parameters</h3>
Zoltan supports the most common parameters in ParMETIS and Jostle. These
parameters are parsed in the package-specific wrapper routine (<b>Zoltan_ParMetis</b>
or <b>Zoltan_Jostle</b>) and later passed on to the desired library via <b>Zoltan_ParMetis_Jostle</b>.
<p>In addition, Zoltan has one graph parameter of its own: <a href="../ug_html/ug_alg_parmetis.html">CHECK_GRAPH</a>.
This parameter is set in <b>Zoltan_ParMetis_Jostle</b> and specifies the amount
of verification that is performed on the constructed graph. For example, it
is required that the graph is symmetric and that the weights are non-negative.
<h3>
Main routine</h3>
The main routine is <b>Zoltan_ParMetis_Jostle</b> but it should always be accessed
through either <b>Zoltan_ParMetis</b> or <b>Zoltan_Jostle</b>.
<p>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_phg.html">Next:&nbsp;
Hypergraph Partitioning</a>&nbsp; |&nbsp; <a href="dev_rib.html">Previous:&nbsp;
Recursive Inertial Bisection (RIB)</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

504
thirdParty/Zoltan/docs/dev_html/dev_phg.html vendored Normal file
View File

@ -0,0 +1,504 @@
<!-------- @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.76 [en] (X11; U; Linux 2.4.2-2smp i686) [Netscape]">
<meta name="sandia.approved" content="SAND99-1377">
<meta name="author" content="karen devine, kddevin@sandia.gov">
<title>Zoltan Developer's Guide: Hypergraph Partitioning</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_reftree.html">Next</a>&nbsp; |&nbsp; <a
href="dev_parmetis.html">Previous</a></i></b></div>
<h2>
<a name="Hypergraph Partitioning"></a>Appendix: Hypergraph Partitioning</h2>
Hypergraph partitioning is a useful partitioning and
load balancing method when connectivity data is available. It can be
viewed as a more sophisticated alternative to
the traditional graph partitioning.
<p>A hypergraph consists of vertices and hyperedges. A hyperedge
connects
one or more vertices. A graph is a special case of a hypergraph where
each edge has size two (two vertices). The hypergraph model is well
suited to parallel computing, where vertices correspond to data objects
and hyperedges represent the communication requirements. The basic
partitioning problem is to partition the vertices into <i>k</i>
approximately equal sets such that the number of cut hyperedges is
minimized. Most partitioners (including Zoltan-PHG) allows a more
general
model where both vertices and hyperedges can be assigned weights.
It has been
shown that the hypergraph model gives a more accurate representation
of communication cost (volume) than the graph model. In particular,
for sparse matrix-vector multiplication, the hypergraph model
<strong>exactly</strong> represents communication volume. Sparse
matrices can be partitioned either along rows or columns;
in the row-net model the columns are vertices and each row corresponds
to an hyperedge, while in the column-net model the roles of vertices
and hyperedges are reversed. </p>
<p>Zoltan contains a native parallel hypergraph partitioner, called PHG
(Parallel HyperGraph partitioner). In addition, Zoltan provides
access to <a href="https://bmi.osu.edu/%7Eumit/software.htm">PaToH</a>,
a serial hypergraph partitioner.
Note that PaToH is not part of Zoltan and should be obtained
separately from the <a href="https://bmi.osu.edu/%7Eumit/software.htm">
PaToH web site</a>.
Zoltan-PHG is a fully parallel multilevel hypergraph partitioner. For
further technical description, see <a
href="ug_refs.html#hypergraph-ipdps06">[Devine et al, 2006]</a>.<br>
</p>
<h4>Algorithm:</h4>
The algorithm used is multilevel hypergraph partitioning. For
coarsening, several versions of inner product (heavy connectivity)
matching are available.
The refinement is based on Fiduccia-Mattheysis (FM) but in parallel it
is only an approximation.
<h4>Parallel implementation:</h4>
A novel feature of our parallel implementation is that we use a 2D
distribution of the hypergraph. That is, each processor owns partial
data about some vertices and some hyperedges. The processors are
logically organized in a 2D grid as well. Most communication is limited
to either a processor row or column. This design should allow for
good scalability on large number of processors.<br>
<h4>Data structures:</h4>
The hypergraph is the most important data structure. This is stored as
a compressed sparse matrix. Note that in parallel, each processor owns
a local part of the global hypergraph
(a submatrix of the whole matrix).
The hypergraph data type is <i>struct HGraph</i>, and contains
information like number of vertices, hyperedges, pins, compressed
storage of all pins, optional vertex and edge weights, pointers
to relevant communicators, and more. One cryptic notation needs an
explanation: The arrays <i>hindex, hvertex</i> are used to
look up vertex info given a hyperedge, and <i>vindex, vedge</i> are
used to look up hyperedge info given a vertex. Essentially,
we store the hypergraph as a sparse matrix in both CSR and CSC formats.
This doubles the memory cost but gives better performance.
The data on each processor is stored using local indexing, starting at zero.
In order to get the global vertex or edge number, use the macros
<i>VTX_LNO_TO_GNO</i> and <i>EDGE_LNO_TO_GNO</i>. These macros will
look up the correct offsets (using the dist_x and dist_y arrays).
Note that <i>phg->nVtx</i> is always the local number of vertices,
which may be zero on some processors.
<h4>Parameters:</h4>
In the User's Guide, only the most essential parameters have been
documented. There are several other parameters, intended for developers
and perhaps expert "power" users. We give a more complete list of all
parameters below. Note that these parameters <span
style="font-style: italic;">may change in future versions!<br>
</span>
For a precise list of parameters in a particular version of Zoltan, look at the source code (phg.c).
<table nosave="" width="100%">
<tbody>
<tr>
<td valign="top"><b>Method String:</b></td>
<td><b>HYPERGRAPH</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td><br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp;&nbsp; <span
style="font-style: italic;">HYPERGRAPH_PACKAGE</span><br>
</td>
<td style="vertical-align: top;">PHG (parallel) or PaToH (serial)<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp; <span
style="font-style: italic;">CHECK_HYPERGRAPH</span><br>
</td>
<td style="vertical-align: top;">Check if input data is valid.
(Slows performance;intended for debugging.)<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;"><span style="font-style: italic;">&nbsp;&nbsp;&nbsp;
PHG_OUTPUT_LEVEL</span><br>
</td>
<td style="vertical-align: top;">Level of verbosity; 0 is silent.<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp;&nbsp; <span
style="font-style: italic;">PHG_FINAL_OUTPUT</span><br>
</td>
<td style="vertical-align: top;">Print stats about final
partition? (0/1)<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp;&nbsp; <span
style="font-style: italic;">PHG_NPROC_VERTEX</span><br>
</td>
<td style="vertical-align: top;">Desired number of processes in
the vertex direction (for 2D internal layout) </td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp;&nbsp; <span
style="font-style: italic;">PHG_NPROC_HEDGE</span><br>
</td>
<td style="vertical-align: top;">Desired number of processes in
the hyperedge direction (for 2D internal layout) </td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp;&nbsp; PHG_COARSENING_METHOD</i></td>
<td>The method to use in matching/coarsening; currently these are
available.&nbsp; <br>
<span style="font-style: italic;">agg</span> - agglomerative inner product
matching (a.k.a. heavy connectivity matching) <br>
<span style="font-style: italic;">ipm</span> - inner product
matching (a.k.a. heavy connectivity matching) <br>
<span style="font-style: italic;">c-ipm</span> -&nbsp; column
ipm;&nbsp; faster method based on ipm within processor columns <br>
<span style="font-style: italic;">a-ipm </span>- alternate
between fast method (l-ipm ) and ipm <br>
<span style="font-style: italic;">l-ipm </span>-&nbsp; local ipm
on each processor. Fastest option&nbsp; but often gives poor quality. <br>
<i>h-ipm - </i>hybrid ipm that&nbsp; uses partial c-ipm followed
by ipm on each level <br>
<i><br>
</i></td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp; <span style="font-style: italic;">PHG_COARSENING_LIMIT</span><br>
</td>
<td>Number of vertices at which to stop coarsening.<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp;&nbsp; <span
style="font-style: italic;">PHG_VERTEX_VISIT_ORDER</span><br>
</td>
<td style="vertical-align: top;">Ordering of vertices in greedy
matching scheme:<br>
0 - random<br>
1 - natural order (as given by the query functions)<br>
2 - increasing vertex weights<br>
3 - increasing vertex degree<br>
4 - increasing vertex degree, weighted by pins<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp;&nbsp; <span
style="font-style: italic;">PHG_EDGE_SCALING</span><br>
</td>
<td style="vertical-align: top;">Scale edge weights by some
function of size of the hyperedges:<br>
0 - no scaling<br>
1 - scale by 1/(size-1)&nbsp;&nbsp;&nbsp;&nbsp; [absorption scaling]<br>
2 - scale by 2/((size*size-1)) [clique scaling]<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp;&nbsp; <span
style="font-style: italic;">PHG_VERTEX_SCALING</span><br>
</td>
<td style="vertical-align: top;">Variations in "inner product"
similarity metric (for matching):<br>
0 - Euclidean inner product: &lt;x,y&gt;<br>
1 - cosine similarity: &lt;x,y&gt;/(|x|*|y|)<br>
2 - &lt;x,y&gt;/(|x|^2 * |y|^2)<br>
3 - scale by sqrt of vertex weights<br>
4 - scale by vertex weights<br>
</td>
</tr>
<tr>
<td valign="top">&nbsp;&nbsp;&nbsp; <i>PHG_COARSEPARTITION_METHOD</i></td>
<td>Method to partition the coarsest (smallest) hypergraph;
typically done in serial:<br>
<span style="font-style: italic;">random</span> - random<br>
<span style="font-style: italic;">linear</span> - linear
(natural) order<br>
<span style="font-style: italic;">greedy </span>- greedy method
based on minimizing cuts<br>
<span style="font-style: italic;">auto </span>- automatically
select from the above methods (in parallel, the processes will do
different methods)<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp;&nbsp; <span
style="font-style: italic;">PHG_REFINEMENT_METHOD</span><br>
</td>
<td style="vertical-align: top;">Refinement algorithm:<br>
&nbsp;<span style="font-style: italic;">fm </span>- two-way
approximate&nbsp; FM<br>
<span style="font-style: italic;">none</span> - no refinement<br>
</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp; <i>PHG_REFINEMENT_LOOP_LIMIT</i></td>
<td>Loop limit in FM refinement. Higher number means more
refinement. <br>
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <span style="font-style: italic;">PHG_REFINEMENT_MAX_NEG_MOVE</span><br>
</td>
<td nosave="">Maximum number of negative moves allowed in FM.<br>
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp; <span style="font-style: italic;">PHG_BAL_TOL_ADJUSTMENT</span><br>
</td>
<td nosave="">Controls how the balance tolerance is adjusted at
each level of bisection.<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp; <span
style="font-style: italic;">PHG_RANDOMIZE_INPUT</span><br>
</td>
<td style="vertical-align: top;">Randomize layout of vertices and
hyperedges in internal parallel 2D layout? (0/1)<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp; <a
name="PHG_EDGE_WEIGHT_OPERATION"></a><span style="font-style: italic;">PHG_EDGE_WEIGHT_OPERATION</span>
</td>
<td style="vertical-align: top;">Operation to be applied to edge
weights supplied by different processes for the same hyperedge:<br>
<i>add</i> - the hyperedge weight will be the sum of the supplied
weights<br>
<i>max</i> - the hyperedge weight will be the maximum of the
supplied weights<br>
<i>error</i> - if the hyperedge weights are not equal, Zoltan
will flag an error, otherwise the hyperedge weight will be the value
returned by the processes<br>
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp; <span style="font-style: italic;">EDGE_SIZE_THRESHOLD</span><br>
</td>
<td nosave="">Ignore hyperedges greater than this fraction times
number of vertices.<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp; <span
style="font-style: italic;">PATOH_ALLOC_POOL0</span><br>
</td>
<td style="vertical-align: top;">Memory allocation for PaToH; see
the PaToH manual for details.<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp; <span
style="font-style: italic;">PATOH_ALLOC_POOL1</span><br>
</td>
<td style="vertical-align: top;">Memory allocation for PaToH; see
the PaToH manual for details.</td>
</tr>
<tr>
<td valign="top"><b>Default values:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><i>HYPERGRAPH_PACKAGE = PHG<br>
</i></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">CHECK_HYPERGRAPH</span>
= 0<br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><span style="font-style: italic;">PHG_OUTPUT_LEVEL=0</span></td>
</tr>
<tr>
<td><br>
</td>
<td><span style="font-style: italic;">PHG_FINAL_OUTPUT=0</span></td>
</tr>
<tr>
<td><br>
</td>
<td><i>PHG_REDUCTION_METHOD=ipm</i></td>
</tr>
<tr>
<td><br>
</td>
<td><span style="font-style: italic;">PHG_REDUCTION_LIMIT=100</span></td>
</tr>
<tr>
<td><br>
</td>
<td><span style="font-style: italic;">PHG_VERTEX_VISIT_ORDER=0</span></td>
</tr>
<tr>
<td><br>
</td>
<td><span style="font-style: italic;">PHG_EDGE_SCALING=0</span></td>
</tr>
<tr>
<td><br>
</td>
<td><span style="font-style: italic;">PHG_VERTEX_SCALING=0</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><i>PHG_COARSEPARTITION_METHOD=greedy</i></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">PHG_REFINEMENT_METHOD=fm</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><i>PHG_REFINEMENT_LOOP_LIMIT=10</i></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">PHG_REFINEMENT_MAX_NEG_MOVE=100</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">PHG_BAL_TOL_ADJUSTMENT=0.7</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">PHG_RANDOMIZE_INPUT=0</span></td>
</tr>
<tr>
<td><br>
</td>
<td><span style="font-style: italic;">PHG_EDGE_WEIGHT_OPERATION=max</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">EDGE_SIZE_THRESHOLD=0.25</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">PATOH_ALLOC_POOL0=0</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">PATOH_ALLOC_POOL1=0</span></td>
</tr>
<tr>
<td valign="top"><b>Required Query Functions:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="../ug_html/ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
or <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</td>
</tr>
<tr nosave="" valign="top">
<td><br>
</td>
<td nosave=""> <b><a href="../ug_html/ug_query_lb.html#ZOLTAN_HG_SIZE_CS_FN">ZOLTAN_HG_SIZE_CS_FN</a></b>
<br>
<b><a href="../ug_html/ug_query_lb.html#ZOLTAN_HG_CS_FN">ZOLTAN_HG_CS_FN</a></b>
</td>
</tr>
<tr>
<td valign="top"><b>Optional Query Functions:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="../ug_html/ug_query_lb.html#ZOLTAN_HG_SIZE_EDGE_WTS_FN">ZOLTAN_HG_SIZE_EDGE_WTS_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="../ug_html/ug_query_lb.html#ZOLTAN_HG_EDGE_WTS_FN">ZOLTAN_HG_EDGE_WTS_FN</a></b></td>
</tr>
</tbody>
</table>
<p>
It is possible to provide the graph query functions instead of the
hypergraph queries, though this is not recommended. If only graph query
functions are registered, Zoltan will automatically create a hypergraph
from the graph, but some information (specifically, edge weights) will
be lost. </p>
<hr width="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a
href="dev_reftree.html">Next:&nbsp;
Refinement Tree Partitioning</a>&nbsp; |&nbsp; <a
href="dev_parmetis.html">Previous:&nbsp;
ParMetis</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

207
thirdParty/Zoltan/docs/dev_html/dev_rcb.html vendored Normal file
View File

@ -0,0 +1,207 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 5.6 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: RCB</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_rib.html">Next</a>&nbsp; |&nbsp; <a href="dev_test_script.html">Previous</a></i></b></div>
<H2>
<A NAME="RCB"></A>Appendix: Recursive Coordinate Bisection (RCB)</H2>
&nbsp;
<H3>
Outline of Algorithm</H3>
<P>The implementation of Recursive Coordinate Bisection (RCB) in Zoltan
is due to Steve Plimpton of Sandia National Laboratories and was modified
by Matt St. John and Courtenay Vaughan. In this implementation of RCB, the
parallel computer is first divided into two pieces and then the computational
domain is divided into two pieces such that the proportion of work in each
piece is the same as the proportion of computational power. The division
of the parallel machine is done by a subroutine which is part of the support
for heterogenous architectures that is being built into the Zoltan library.
This process is repeated recursively on each subdomain and its associated
part of the computer. Each of these divisions are done with a cutting plane
that is orthogonal to one of the coordinate axes.
<P>At each of these stages, each subdomain of processors and the objects
that are contained on those processors are divided into two sets based
on which side of the cutting plane each object is on. Either or both of
these sets may be empty. On each processor, the set of objects which are
on the same side of the cut as the processor are retained by the processor,
while the other objects are sent to processors on the other side of the
cut. In order to minimize the maximum memory usage in each set of processors,
the objects that are being sent to each set of processors are distributed
such that each each processor in a set has about the same number of objects
after the objects from the other set of processors are sent. In the case
when a processor has more objects that it will retain than the average
number of objects that the rest of the processors have in its set, then
that processor will not receive any objects. Thus each processor may send
and receive objects from several (or no) processors in the other set. The
process of determining which outgoing objects are sent to which processors
is determined in the subroutine <B>Zoltan_Create_Proc_List</B>. Once this new
distribution of objects is determined, the
<B><A HREF="../ug_html/ug_util_comm.html">unstructured communication package</A></B> in
Zoltan is used to determine which processors are going to receive which
objects and actually move the objects.
<P>For applications that wish to add more objects to the decomposition
at a later time (e.g., through <a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Box_Assign"><b>Zoltan_LB_Box_Assign</b></a> or <a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Point_Assign"><b>Zoltan_LB_Point_Assign</b></a>), information to do this can be retained during the
decomposition phase. This information is kept if the parameter <a href="../ug_html/ug_alg_rcb.html">KEEP_CUTS</a>
is set during the decomposition (see the <a href="../ug_html/ug_alg_rcb.html">RCB section</a> in the
<B><A HREF="../ug_html/ug.html">Zoltan User's Guide</A></B>).
This information about the decomposition can be thought of as a tree with
the nodes which have children representing the cut information and the nodes
with no children representing processors. An object is dropped through the
tree starting with the root node and uses the cut information at each node it
encounters to determine which subtree it traverses. When it reaches a terminal
node, the node contains the processor number that the object belongs to.
The information to construct the tree is saved during the decomposition.
At each step in the decomposition, when each set is divided into two sets,
the set with the lowest numbered processor is designated to be the left set
and the information about the cut is stored in the lowest numbered processor
in the other set of processors which is the right set. As a result of this
process, each processor will store information for, at most, one cut, since
once a processor stores information about a cut, by being the lowest numbered
processor in the right set, it will always be in a left set after each
subsequent cut since it will be the lowest numbered processor in the set
being cut and the set it is put into will be the left set. The processor
which stores the cut information also stores the root node as its parent.
After the end of the division process, all of the information is collected
onto all of the processors. The parent information is then used to establish
the leaf information for the parent. When this information is gathered, the
tree structure is stored in arrays with the array position determined by the
processor number that was storing the information. There is an array which
stores the position of the cut information for the left set and one for the
right set as well as arrays for the cut information. Given that the lowest
numbered processor after a cut is in the left set, the cut information is
stored in the right set, and there is one fewer cut than the total number of
processors, processor 0 has no cut information, so the 0 position of the right
set array is empty and is used to store the position in the array that the
first cut is stored. When this information is used to process an object,
array position 0 in the right set array is used to determine the array
position of the first cut. From there, which side of the cut the object is
on is determined and that information is used to determine which cut to test
the object against next. This process is repeated recursively until a
terminal node is encountered which contains the processor number that the
object belongs to.
<p>
When the parameter <a href="../ug_html/ug_alg_rcb.html">RCB_REUSE</a> is
specified, the RCB algorithm attempts to use information from a previous
RCB decomposition to generate an "initial guess" at the new decomposition.
For problems that change little between invocations of RCB, using <a href="../ug_html/ug_alg_rcb.html">RCB_REUSE</a>
can reduce the amount of data movement in RCB, improving the performance
of the algorithm. When <a href="../ug_html/ug_alg_rcb.html">RCB_REUSE</a> is true,the coordinates of all objects obtained through query functions are passed through
<a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Point_Assign"><b>Zoltan_LB_Point_Assign</b></a>
to determine their processor assignment in the previous RCB decomposition.
The information for the objects is then sent to the new processor assignments
using the <a href="../ug_html/ug_util_comm.html">unstructured communication utilities</a>
to generate an initial condition matching the output of the previous RCB
decomposition.
The normal RCB algorithm is then applied to this new initial condition.
<BR>&nbsp;
<H3>
Data Structure Definitions</H3>
<P>There are three major data structures in RCB and they are defined in
<i>rcb/rcb.h</i> and <i>rcb/shared.h</i>. The points which are being load balanced are represented as a
structure <i>Dot_Struct</i> which contains the location of the point, its weight, and
its originating processor number. The nodes on the decomposition tree are
represented by the structure <i>rcb_tree</i> which contains the position of the cut,
the dimension that the cut is perpendicular to, and the node's parent and two
children (if they exist) in the tree. The structure <i>RCB_Struct</i> is the RCB data
structure which holds pointers to all of the other data structures needed for
RCB. It contains an array of <i>Dot_Struct</i> to represent the points being load
balanced, global and local IDs for the points, and an array of <i>rcb_tree</i> (whose length is the number of processors)
which contains the decomposition tree.
<BR>&nbsp;
<H3>
Parameters</H3>
<P>The parameters used by RCB and their default values are described in the
<a href="../ug_html/ug_alg_rcb.html">RCB section</a> of the <B><A HREF="../ug_html/ug.html">Zoltan User's
Guide</A></B>. These can be set by use of the <b>Zoltan_RCB_Set_Param</b> subroutine
in the file <i>rcb/rcb.c</i>.
<p>
When the parameter <a href="../ug_html/ug_alg_rcb.html">REDUCE_DIMENSIONS</a>
is specified, the RCB algorithm will perform lower dimensional
partitioning if the geometry is found to be degenerate. More information
on detecting degenerate
geometries may be found in another <a href="dev_degenerate.html">
section</a>.
<BR>&nbsp;
<H3>
Main Routine</H3>
<P>The main routine for RCB is <b>Zoltan_RCB</b> in the file <i>rcb/rcb.c</i>.
<BR>&nbsp;
<BR>&nbsp;
<BR>&nbsp;
<P>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of
Contents</A>&nbsp; |&nbsp; <a href="dev_rib.html">Next:&nbsp;
Recursive Inertial Bisection (RIB)</a>&nbsp; |&nbsp; <A HREF="dev_test_script.html">
Previous:&nbsp; Using the Test Script</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

108
thirdParty/Zoltan/docs/dev_html/dev_refs.html vendored Normal file
View File

@ -0,0 +1,108 @@
<!-------- @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: References</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_driver.html">Next</a>&nbsp; |&nbsp; <a href="dev_cpp.html">Previous</a></i></b></div>
<h2>
<a NAME="refs"></a>References</h2>
<ol>
<li>
<a NAME="BB87"></a>M. J. Berger and S. H. Bokhari. "A partitioning strategy
for nonuniform problems on multiprocessors." <i>IEEE Trans. Computers</i>,
C-36 (1987), 570-580.</li>
<li>
<a NAME="Users_Guide"></a>K. Devine, B. Hendrickson, M. St.John, E. Boman,
and C. Vaughan. "<a href="../ug_html/ug.html">Zoltan: A Dynamic Load-Balancing
Library for Parallel Applications, User's Guide.</a>" Sandia National Laboratories
Tech. Rep. SAND99-1377, Albuquerque, NM, 1999.</li>
<li>
<a NAME="E97"></a>H. C. Edwards. <i>A Parallel Infrastructure For Scalable
Adaptive Finite Element Methods and Its Application To Least Squares C^(inf)
Collocation</i>. Ph.D. Dissertation, University of Texas at Austin, May,
1997.</li>
<li>
<a NAME="HD99"></a>B. Hendrickson and K. Devine. "Dynamic Load Balancing
in Computational Mechanics." <i>Comp. Meth. Appl. Mech. Engrg.</i>, <b>184</b>
(2000) 484-500.</li>
<li>
<a NAME="Chaco"></a>B. Hendrickson and R. Leland.&nbsp; ``The Chaco User's
Guide, version 2.0.''&nbsp; Sandia National Laboratories Tech. Rep. SAND94-2692,
Albuquerque, NM, 1994.&nbsp; <a href="http://cs.sandia.gov/CRF/chac.html">http://cs.sandia.gov/CRF/chac.html</a></li>
<li>
<a NAME="ParMETIS"></a>G. Karypis and V. Kumar.&nbsp; ``ParMETIS:&nbsp;
Parallel graph partitioning and sparse matrix ordering library.''&nbsp;
Tech. Rep. 97-060, Dept. of Computer Science, Univ. of Minnesota, 1997.&nbsp;
<a href="https://www-users.cs.umn.edu/~karypis/metis/parmetis/">https://www-users.cs.umn.edu/~karypis/metis/parmetis/</a></li>
<li>
<a NAME="Jostle"></a>C. Walshaw.&nbsp; "Parallel Jostle Library Interface:&nbsp;
Version 1.1.7."&nbsp; Tech. Rep., Univ. of Greenwich, London, 1995.&nbsp;
<a href="https://www.gre.ac.uk/jostle">https://www.gre.ac.uk/jostle</a></li>
</ol>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_driver.html">Next:&nbsp;
Using Test Driver</a>&nbsp; |&nbsp; <a href="dev_cpp.html">Previous:&nbsp;
C++ Interface</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

163
thirdParty/Zoltan/docs/dev_html/dev_reftree.html vendored Normal file
View File

@ -0,0 +1,163 @@
<!-------- @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="william mitchell, william.mitchell@nist.gov">
<title> Zoltan Developer's Guide: Refinement Tree</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_hsfc.html">Next</a> &nbsp;
|&nbsp; <a href="dev_phg.html">Previous</a></i></b></div>
<h2>
Appendix: Refinement Tree</h2>
<h3>
Overview of structure (algorithm)</h3>
The refinement tree based partitioning algorithm was developed and implemented
by <a href="https://math.nist.gov/~mitchell">William Mitchell</a> of the National Institute of Standards and Technology.
It is similar to the Octree method except that it uses a tree representation
of the refinement history instead of a geometry based octree. The method
generates a space filling curve which is cut into <i>K</i> appropriately-sized pieces
to define contiguous parts, where the size of a piece is the sum of the
weights of the elements in that piece. <i>K</i>, the number of parts, is not
necessarily equal to <i>P</i>, the number of processors. It is an appropriate load balancing
method for grids that are generated by adaptive refinement when the refinement
history is available. This implementation consists of two phases: the
construction of the refinement tree, and the definition of the parts.
<h4>
Refinement Tree Construction</h4>
The refinement tree consists of a root node and one node for each element
in the refinement history. The children of the root node are the elements
of the initial coarse grid. The children of all other nodes are the elements
that were formed when the parent element was refined. Upon first invocation,
the refinement tree is initialized. This creates the root node and initializes
a hash table that maps global IDs into nodes of the refinement tree.
It also queries the user for the elements of the initial grid and creates
the children of the root node. Unless the user provides the order
through which to traverse the elements of the initial grid, a path is
determined through the initial elements along with the "in" vertex and
"out" vertex of each element, i.e., the vertices through which the path
passes to move from one element to the next.
This path can be determined by a Hilbert space filling curve, Sierpinski
space filling curve (triangles only), or an algorithm that attempts to make
connected parts (connectivity is guaranteed for triangles and
tetrahedra).
The refinement tree is required to have all initial coarse grid elements,
not just those that reside on the processor. However, this requirement is not
imposed on the user; a communication step fills in the elements from other
processors. This much of the tree persists throughout execution of the
program. The remainder of the tree is reconstructed on each invocation of
the refinement tree partitioner. The remainder of the tree is built through
a tree traversal. At each node, the user is queried for the children of the
corresponding element. If there are no children, the user is queried for
the weight of the element. If there are children, the order of the children
is determined such that a tree traversal produces a space filling curve.
The user indicates what type of refinement was used to produce the children
(bisection of triangles, quadrasection of quadrilaterals, etc.). For each
supported type of refinement, a template based ordering is imposed. The
template also maintains an "in" and "out" vertex for each element
which are used by the template to determine the beginning and end of the space
filling curve through the children. If the
refinement is not among the types supported by templates, an exhaustive
search is performed to find an appropriate order, unless the user provides
the order.
<h4>
Partition algorithm</h4>
The algorithm that determines the parts uses four traversals of the
refinement tree. The first two traversals sum the weights in the tree.
In the first traversal, each node gets the sum of the weights of all the
descendant nodes that are assigned to this processor. The processors then
exchange information to fill in the partial sums for the leaf elements
that are not owned by this processor. (Note that an unowned leaf on one
processor may be the root of a large subtree on another processor.)
The second traversal completes the summation of the weights. The root
now has the sum of all the weights, which, in conjunction with an array
of relative part sizes, determines the desired weight of each part.
Currently the array of part sizes are all equal, but in the future
the array will be input to reflect heterogeneity in the system. The third
traversal computes the partition by adding subtrees to a part
until the size of the part meets the desired weight, and counts
the number of elements to be exported. Finally, the fourth traversal
constructs the export list.
<h3>
Data structures</h3>
The implementation of the refinement tree algorithm uses three data
structures which are contained in <i>reftree/reftree.h</i>. <i>Zoltan_Reftree_data_struct</i>
is the structure pointed to by <i>zz->LB.Data_Structure</i>. It contains a pointer
to the refinement tree root and a pointer to the hash table.
<i>Zoltan_Reftree_hash_node</i> is an entry in the hash table. It consists of a global ID,
a pointer to a refinement tree node, and a "next" pointer from which
linked lists at each table entry are constructed to handle collisions.
<i>Zoltan_Reftree_Struct</i> is
a node of the refinement tree. It contains the global ID, local ID,
pointers to the children, weight and summed weights, vertices of the
element, "in" and "out" vertex, a flag to indicate if this element is
assigned to this processor, and the new part number.
<h3>
Parameters</h3>
There are two parameters. <a href="../ug_html/ug_alg_reftree.html">REFTREE_HASH_SIZE</a> determines the size of
the hash table.
<a href="../ug_html/ug_alg_reftree.html">REFTREE_INITPATH</a> determines which
algorithm to use to find a path through the initial elements.
Both are set by <b>Zoltan_Reftree_Set_Param</b> in the file <i>reftree/reftree_build.c</i>.
<h3>
Main routine</h3>
The main routine is <b>Zoltan_Reftree_Part</b> in file <i>reftree/reftree_part.c</i>.
<p>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp;
|&nbsp; <a href="dev_hsfc.html">Next: &nbsp; Hilbert Space-Filling Curve (HSFC)</a>
|&nbsp; <a href="dev_phg.html">Previous:&nbsp; Hypergraph Partitioning</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

146
thirdParty/Zoltan/docs/dev_html/dev_rib.html vendored Normal file
View File

@ -0,0 +1,146 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 5.6 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: RIB</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_parmetis.html">Next</a>&nbsp; |&nbsp; <a href="dev_rcb.html">Previous</a></i></b></div>
<H2>
<A NAME="RIB"></A>Appendix: Recursive Inertial Bisection (RIB)</H2>
<H3>
Outline of Algorithm</H3>
<P>The implementation of Recursive Inertial Bisection (RIB) in Zoltan is due
due to Bruce Hendrickson and Robert Leland of Sandia National Laboratories for
use in <a href="http://cs.sandia.gov/CRF/chac.html">Chaco</a>
and was modified by Courtenay Vaughan. RIB is an algorithm
similar to RCB (see the <B><A HREF="dev_rcb.html">appendix on RCB</A></B> for
a description of RCB) in that it uses the coordinates of the objects to be
balanced to do the load balancing. Similarly to RCB, the domain is
recursively divided into two pieces until the number of subdomains needed is
reached. In each stage of the division, the direction of the principle axis
of the domain to be divided is calculated by determining an eigenvector of
the inertial matrix. This direction vector is used to define a normal to a
plane which is used to divide the domain into two pieces. This process is
repeated until the desired number of subdomains is reached.
<P>The communication of objects being divided is handled by the same routine
as is used by <B><A HREF="dev_rcb.html">RCB</A></B>. For applications which
wish to add more objects to the decomposition at a later time
(e.g., through <a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Box_Assign"><b>Zoltan_LB_Box_Assign</b></a> or
<a href="../ug_html/ug_interface_augment.html#Zoltan_LB_Point_Assign"><b>Zoltan_LB_Point_Assign</b></a>),
information to
do this can be retained during the decomposition phase. This information is
kept if the parameter <a href="../ug_html/ug_alg_rib.html">KEEP_CUTS</a> is set during the decomposition.
The process is similar to that used for RCB, but the
information kept is different. For each RIB cut, the center of mass
of the subdomain which is cut, the direction vector, and a distance from
the center of mass to the cutting plane have to be saved.
<BR>&nbsp;
<H3>
Data Structure Definitions</H3>
<P>There are three major data structures in RIB and they are defined in
<i>rcb/rib.h</i> and <i>rcb/shared.h</i>. The points which are being load balanced are represented as a
structure <i>Dot_Struct</i> which contains the location of the point, its weight, and
the originating processor's number. The nodes on the decomposition tree are
represented by the structure <i>rib_tree</i> which contains the position of the cut,
the center of mass of the subdomain which is being cut, the direction vector
of the principle axis of the subdomain, and the node's parent and two
children (if they exist) in the tree. The structure RIB_Struct is the RIB data
structure which holds pointers to all of the other data structures needed for
RIB. It contains an array of <i>Dot_Struct</i> to represent the points being load
balanced, global and local IDs of the points, an array of <i>rib_tree</i> (whose length is the number of processors) which
contains the decomposition tree, and the dimension of the problem.
<BR>&nbsp;
<H3>
Parameters</H3>
<P>The parameters used by RIB and their default values are described in the
<a href="../ug_html/ug_alg_rib.html">RIB</a> section of the <B><A HREF="../ug_html/ug.html">Zoltan User's
Guide</A></B>. These can be set by use of the <b>Zoltan_RIB_Set_Param</b> subroutine
in the file <i>rcb/rib.c</i>.
<p>
When the parameter <a href="../ug_html/ug_alg_rib.html">REDUCE_DIMENSIONS</a>
is specified, the RIB algorithm will perform lower dimensional
partitioning if the geometry is found to be degenerate. More information
on detecting degenerate
geometries may be found in another <a href="dev_degenerate.html">
section</a>.
<BR>&nbsp;
<H3>
Main Routine</H3>
<P>The main routine for RIB is <b>Zoltan_RIB</b> in the file <i>rcb/rib.c</i>.
<BR>&nbsp;
<BR>&nbsp;
<BR>&nbsp;
<P>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of
Contents</A>&nbsp; |&nbsp; <a href="dev_parmetis.html">Next:&nbsp; ParMETIS and
Jostle</a>&nbsp; |&nbsp; <A HREF="dev_rcb.html">Previous:&nbsp; Recursive
Coordinate Bisection (RCB)</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

78
thirdParty/Zoltan/docs/dev_html/dev_services.html vendored Normal file
View File

@ -0,0 +1,78 @@
<!-------- @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: Services</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_services_params.html">Next</a>&nbsp; |&nbsp; <a href="dev_lb_structs.html">Previous</a></i></b></div>
<h2>
<a NAME="services"></a>Services</h2>
Within Zoltan, several services are provided to simplify development of new algorithms
in the library.&nbsp; Each service consists of a routine or set of routines that is
compiled directly into Zoltan.&nbsp; Use of these services makes debugging easier
and provides a uniform look to the algorithms in the library.&nbsp; The
services available are listed below.
<blockquote>
<br><a href="dev_services_params.html">Parameter Setting Routines</a>
<br><a href="dev_services_parallel.html">Parallel Computing Routines</a>
<br><a href="dev_services_objlist.html">Object List Function</a>
<br><a href="dev_services_hash.html">Hash Function</a>
<br><a href="dev_services_time.html">Timing Routines</a>
<br><a href="dev_services_debug.html">Debugging Services</a></blockquote>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_services_params.html">Next:&nbsp;
Parameter Setting Routines</a>&nbsp; |&nbsp; <a href="dev_lb_structs.html">Previous:&nbsp; Data Structures</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

278
thirdParty/Zoltan/docs/dev_html/dev_services_debug.html vendored Normal file
View File

@ -0,0 +1,278 @@
<!-------- @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: Debugging Services</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_add.html">Next</a>&nbsp; |&nbsp; <a href="dev_services_zoltantimer.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->
<h2>
<a NAME="Debugging"></a>Debugging Services</h2>
Execution of code for debugging can be controlled by algorithm specific
parameters or by the Zoltan key parameter <a href="../ug_html/ug_param.html#Debug Levels in Zoltan">DEBUG_LEVEL</a>.
The value of the <i>Debug_Level</i> field of the <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
structure can be tested to determine whether the user desires debugging
information.&nbsp; Several constants (<b>ZOLTAN_DEBUG_*</b>) are defined in
<i>zz/zz_const.h</i>; the <i>Debug_Level</i> field should be compared to
these values so that future changes to the debugging levels can be made
easily.&nbsp; An <a href="#Debug Example">example</a> is included below.
<p>Several macros for common debugging operations are provided.&nbsp; The
macros can be used to generate function trace information, such as when
control enters or exits a function or reaches a certain point in the execution
of a function.
<blockquote><a href="#ZOLTAN_TRACE_ENTER">ZOLTAN_TRACE_ENTER</a>
<br><a href="#ZOLTAN_TRACE_EXIT">ZOLTAN_TRACE_EXIT</a>
<br><a href="#ZOLTAN_TRACE_DETAIL">ZOLTAN_TRACE_DETAIL</a></blockquote>
These macros produce output depending upon the value of the <a href="../ug_html/ug_param.html#Debug Levels in Zoltan">DEBUG_LEVEL</a>
parameter set in Zoltan by a call to <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.&nbsp;&nbsp;
The macros are defined in <i>zz/zz_const.h.</i>
<p><a href="#Debug Example">Examples</a> of the use of these macros can
be found <a href="#Debug Example">below</a> and in <i>lb/lb_balance.c</i>
and <i>rcb/rcb.c.</i>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="ZOLTAN_TRACE_ENTER"></a>
<hr>
<b>ZOLTAN_TRACE_ENTER</b>(struct <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
*<i>zz</i>, char *<i>function_name</i>);
<br>
<hr>
<b>ZOLTAN_TRACE_ENTER</b> prints to <i>stdout</i> a message stating that
a given processor is entering a function.&nbsp; The call to the macro should
be included at the beginning of major functions for which debugging information
is desired.&nbsp; Output includes the processor number and the function
name passed as an argument to the macro.&nbsp; The amount of output produced
is controlled by the value of the <a href="../ug_html/ug_param.html#Debug Levels in Zoltan">DEBUG_LEVEL</a>
parameter set in Zoltan by a call to <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>zz</i></td>
<td>Pointer to a Zoltan structure.
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>&nbsp;&nbsp;&nbsp; <i>function_name</i></td>
<td>Character string containing the function's name.</td>
</tr>
<tr>
<td><b>Output:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;</td>
<td>ZOLTAN (Processor #) Entering <i>function_name</i></td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="ZOLTAN_TRACE_EXIT"></a>
<hr>
<b>ZOLTAN_TRACE_EXIT</b>(struct <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
*<i>zz</i>, char *<i>function_name</i>);
<br>
<hr>
<b>ZOLTAN_TRACE_EXIT</b> prints to <i>stdout</i> a message stating that
a given processor is exiting a function.&nbsp; The call to the macro should
be included at the end of major functions (and before return statements)
for which debugging information is desired.&nbsp; Output includes the processor
number and the function name passed as an argument to the macro.&nbsp;
The amount of output produced is controlled by the value of the <a href="../ug_html/ug_param.html#Debug Levels in Zoltan">DEBUG_LEVEL</a>
parameter set in Zoltan by a call to <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; zz</i></td>
<td>Pointer to a Zoltan structure.
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><i>&nbsp;&nbsp;&nbsp; function_name</i></td>
<td>Character string containing the function's name.</td>
</tr>
<tr>
<td><b>Output:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;</td>
<td>ZOLTAN (Processor #) Leaving <i>function_name</i></td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="ZOLTAN_TRACE_DETAIL"></a>
<hr WIDTH="100%">
<b>ZOLTAN_TRACE_DETAIL</b>(struct
<b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
*<i>zz</i>, char *<i>function_name</i>, char *<i>message</i>);
<br>
<hr>
<b>ZOLTAN_TRACE_DETAIL</b> prints to <i>stdout</i> a message specified
by the developer.&nbsp;&nbsp; It can be used to indicate how far execution
has progressed through a routine.&nbsp; It can also be used to print values
of variables.&nbsp; See the example below.&nbsp; Output includes the processor
number, the function name passed as an argument to the macro, and a user-defined
message passed to the macro.&nbsp; The amount of output produced is controlled
by the value of the <a href="../ug_html/ug_param.html#Debug Levels in Zoltan">DEBUG_LEVEL</a>
parameter set in Zoltan by a call to <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>zz</i></td>
<td>Pointer to a Zoltan structure.
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>&nbsp;&nbsp;&nbsp; <i>function_name</i></td>
<td>Character string containing the function's name.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>&nbsp;&nbsp;&nbsp; <i>message</i></td>
<td>Character string containing a message defined by the developer.</td>
</tr>
<tr>
<td><b>Output:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;</td>
<td>ZOLTAN (Processor #)&nbsp; <i>function_name: message</i></td>
</tr>
</table>
<br>&nbsp;
<br>&nbsp;
<!------------------------------------------------------------------------->
<p>
<hr><a NAME="Debug Example"></a>
<br><b>Example:</b>
<br>An example using the debugging macros in shown below.
<tt>
<ul>#include "zoltan.h"
<br>void example(struct <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
*zz)
<br>{
<br>char *yo = "example";
<br>char tmp[80];
<br>int a, b;
<br>&nbsp;
<ul><a href="#ZOLTAN_TRACE_ENTER">ZOLTAN_TRACE_ENTER</a>(zz, yo);
<br>a = function_one(zz);
<br><a href="#ZOLTAN_TRACE_DETAIL">ZOLTAN_TRACE_DETAIL</a>(zz, yo, "After function_one");
<br>b = function_two(zz);
<br>sprintf(tmp, "b = %d a = %d", b, a);
<br><a href="#ZOLTAN_TRACE_DETAIL">ZOLTAN_TRACE_DETAIL</a>(zz, yo, tmp);
<br>if (zz->Debug_Level >= ZOLTAN_DEBUG_ALL)
<br>&nbsp; printf("Total = %d\n", a+b);
<br><a href="#ZOLTAN_TRACE_EXIT">ZOLTAN_TRACE_EXIT</a>(zz, yo);</ul>
}</ul>
</tt>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_add.html">Next:&nbsp;
Adding New Load-Balancing Algorithms</a> |&nbsp; <a href="dev_services_zoltantimer.html">Previous:&nbsp;
ZOLTAN_TIMER</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

131
thirdParty/Zoltan/docs/dev_html/dev_services_hash.html vendored Normal file
View File

@ -0,0 +1,131 @@
<!-------- @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.6 sun4m) [Netscape]">
<meta name="sandia.approved" content="SAND99-1376">
<meta name="author" content="karen devine, kddevin@sandia.gov">
<title> Zoltan Developer's Guide: Hash function</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_services_time.html">Next</a>&nbsp; |&nbsp; <a href="dev_services_objlist.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->
<h2>
Hash Function</h2>
Zoltan provides a hash function for global and local IDs. The hash function
computes a non-negative integer value in a certain range<i> </i>from an
ID.
<blockquote><b><a href="#Zoltan_Hash">Zoltan_Hash</a></b>&nbsp; : hash a global
or local ID into non-negative integers</blockquote>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Hash"></a>
<hr>
unsigned int<b> Zoltan_Hash</b>(
<b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR
</a></b><i>key</i>,
int <i>num_id_entries</i>, unsigned int <i>n</i>);&nbsp;
<hr>
<b>Zoltan_Hash </b>computes a hash value for a global or local ID. Note
that this hash function has been optimized for 32-bit integer systems,
but should&nbsp; work on any machine. The current implementation uses a
simple multiplicative hash function based on Don Knuth's golden ratio method;
see <i>The Art of&nbsp; Computer Programming,</i> vol. 3.
<br>&nbsp;
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr VALIGN=TOP>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>key</i></td>
<td>A pointer to the ID to be hashed.</td>
</tr>
<tr VALIGN=TOP>
<td>&nbsp;&nbsp;&nbsp; <i>num_id_entries</i></td>
<td>The length of the ID (as given by <b><a href="../ug_html/ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a></b>
or <b><a href="../ug_html/ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a></b>).</td>
</tr>
<tr VALIGN=TOP>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>n</i></td>
<td>The computed hash value will be between 0 and <i>n</i>-1.&nbsp;</td>
</tr>
<tr VALIGN=TOP>
<td><b>Return Value:</b></td>
<td></td>
</tr>
<tr VALIGN=TOP>
<td>&nbsp;&nbsp;&nbsp; unsigned int</td>
<td>The hash value (between 0<i> </i>and <i>n</i>-1).&nbsp;</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_services_time.html">Next:&nbsp;
Timing Routines</a>&nbsp; |&nbsp; <a href="dev_services_objlist.html">Previous:&nbsp;
Object List Function</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

324
thirdParty/Zoltan/docs/dev_html/dev_services_objlist.html vendored Normal file
View File

@ -0,0 +1,324 @@
<!-------- @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.76 [en] (X11; U; Linux 2.4.2-2smp i686) [Netscape]">
<meta name="sandia.approved" content="SAND99-1376">
<meta name="author" content="karen devine, kddevin@sandia.gov">
<title> Zoltan Developer's Guide: Object List function</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_services_hash.html">Next</a>&nbsp; |&nbsp; <a href="dev_services_parallel.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->
<h2>
Common Functions for Querying Applications</h2>
Many Zoltan algorithms need to query applications for similar data.
The following functions provide simple, uniform query functionality for
algorithm developers:
<blockquote>
<b><a href="#Zoltan_Get_Obj_List">Zoltan_Get_Obj_List</a></b><br>
<b><a href="#Zoltan_Get_Coordinates">Zoltan_Get_Coordinates</a></b><br>
</blockquote>
These functions provide a uniform method of calling the query functions
registered by an application.
Their use simplifies new algorithm development and code
maintenance. Usage examples are in <i>rcb/shared.c</i>.
<p><b><a href="#Zoltan_Get_Obj_List">Zoltan_Get_Obj_List</a></b> can be called
from any Zoltan algorithm to obtain a list of object IDs, weights, and
part assignments.
<p>Given a list of object IDs,
<b><a href="#Zoltan_Get_Coordinates">Zoltan_Get_Coordinates</a></b>
can be called from any Zoltan algorithm to obtain a list of coordinates for
those IDs.
<p><b><i>Note that, contrary to most Zoltan functions, these functions allocate
memory for their return lists.</i></b>
<p><!------------------------------------------------------------------------->
<hr><a NAME="Zoltan_Get_Obj_List"></a>
<hr>int<b> Zoltan_Get_Obj_List</b>(
<br>&nbsp;&nbsp;&nbsp; struct <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp; int *<i>num_obj</i>,
<br>&nbsp;&nbsp;&nbsp; <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b> *<i>global_ids</i>,
<br>&nbsp;&nbsp;&nbsp; <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b> *<i>local_ids</i>,
<br>&nbsp;&nbsp;&nbsp; int <i>wdim</i>,
<br>&nbsp;&nbsp;&nbsp; float **<i>objwgts</i>,
<br>&nbsp;&nbsp;&nbsp; int **<i>parts</i>);
<hr><b>Zoltan_Get_Obj_List</b> returns arrays of global and local IDs,
part assignments, and
object weights (if
<b><a href="../ug_html/ug_param.html#General_Parameters">OBJ_WEIGHT_DIM</a></b>
is not zero) for all objects on a processor. It is a convenient function
that frees algorithm developers from calling
<b><a href="../ug_html/ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>,
<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>,
and
<b><a href="../ug_html/ug_query_lb.html#ZOLTAN_PART_FN">ZOLTAN_PART_FN</a></b>
query functions directly.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%" NOSAVE><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>zz</i></td>
<td>A pointer to the Zoltan structure created by <b><a href="../ug_html/ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp; <i>num_obj</i></td>
<td>Upon return,&nbsp; the number of objects.</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp; <i>global_ids</i></td>
<td>Upon return, an array of global IDs of objects on the current processor.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>local_ids</i></td>
<td>Upon return, an array of local IDs of objects on the current processor.
NULL is returned when
<a href="../ug_html/ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>
is zero.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>wdim</i></td>
<td>The number of weights associated with an object (typically 1), or 0
if weights are not requested.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>objwgts</i></td>
<td>Upon return, an array of object weights. Weights for object <i>i</i>
are stored in
<i>objwgts</i>[<i>i</i>*<i>wdim</i>:(<i>i</i>+1)*<i>wdim</i>-1], for
<i>i</i>=0,1,...,<i>num_obj</i>-1.
If <i>wdim</i> is zero, the return value of objwgts is undefined and may
be NULL.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>parts</i></td>
<td>Upon return, an array of part assignments. Object <i>i</i>
is currently in part <i>parts[i]</i>.
</td>
</tr>
<tr>
<td VALIGN=TOP><b>Returned value:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td></td>
<td><b><a href="../ug_html/ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
or <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</td>
</tr>
<tr>
<td VALIGN=TOP><b>Optional Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="../ug_html/ug_query_lb.html#ZOLTAN_PART_FN">ZOLTAN_PART_FN</a></b></td>
</tr>
</table>
<p><!------------------------------------------------------------------------->
<hr><a NAME="Zoltan_Get_Coordinates"></a>
<hr>int<b> Zoltan_Get_Coordinates</b>(
<br>&nbsp;&nbsp;&nbsp; struct <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp; int <i>num_obj</i>,
<br>&nbsp;&nbsp;&nbsp; <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b> <i>global_ids</i>,
<br>&nbsp;&nbsp;&nbsp; <b><a href="../ug_html/ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b> <i>local_ids</i>,
<br>&nbsp;&nbsp;&nbsp; int *<i>num_dim</i>,
<br>&nbsp;&nbsp;&nbsp; double **<i>coords</i>);
<hr>
Given lists of object IDs,
<b>Zoltan_Get_Coordinates</b> returns the dimensionality of the problem and
an array of coordinates of the objects. It is a convenient function
that frees algorithm developers from calling
<b><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a></b>,
<b><a href="../ug_html/ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b>,
and
<b><a href="../ug_html/ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
query functions directly.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%" NOSAVE><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>zz</i></td>
<td>A pointer to the Zoltan structure created by <b><a href="../ug_html/ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp; <i>num_obj</i></td>
<td>The number of objects.</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp; <i>global_ids</i></td>
<td>An array of global IDs of objects on the current processor.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>local_ids</i></td>
<td>An array of local IDs of objects on the current processor.
<i>local_ids</i> is NULL when
<a href="../ug_html/ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>
is zero.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>num_dim</i></td>
<td>Upon return, the number of coordinates for each object (typically 1, 2 or
3).
</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>coords</i></td>
<td>Upon return, an array of coordinates for the objects. Coordinates for
object <i>i</i>
are stored in
<i>coords</i>[<i>i</i>*<i>num_dim</i>:(<i>i</i>+1)*<i>num_dim</i>-1], for
<i>i</i>=0,1,...,<i>num_obj</i>-1.
</td>
</tr>
<tr>
<td VALIGN=TOP><b>Returned value:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="../ug_html/ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a></b></td>
</tr>
<tr>
<td></td>
<td>
<b><a href="../ug_html/ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b>
or
<b><a href="../ug_html/ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
</td>
</tr>
</table>
<p><!------------------------------------------------------------------------->
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_services_hash.html">Next:&nbsp;
Hash Function</a>&nbsp; |&nbsp; <a href="dev_services_parallel.html">Previous:&nbsp;
Parallel Routines</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

254
thirdParty/Zoltan/docs/dev_html/dev_services_parallel.html vendored Normal file
View File

@ -0,0 +1,254 @@
<!-------- @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
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
<META NAME="sandia.approved" CONTENT="SAND99-1376">
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
<TITLE> Zoltan Developer's Guide: Parallel Routines</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_services_objlist.html">Next</a>&nbsp; |&nbsp; <a href="dev_services_params.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->
<H2>
<A NAME="parallel_compute"></A>Parallel Computing Routines</H2>
Parallel computing utilities are described in this section.
<BLOCKQUOTE><B><A HREF="#Zoltan_Print_Sync_Start">Zoltan_Print_Sync_Start</A></B>
/ <B><A HREF="#Zoltan_Print_Sync_End">Zoltan_Print_Sync_End</A></B>:&nbsp; provide
synchronization of processors for I/O (with <A HREF="#print_sync_example">example</A>).
<BR><B><A HREF="#Zoltan_Print_Stats">Zoltan_Print_Stats</A></B> : print statistics
about a parallel variable.</BLOCKQUOTE>
<!------------------------------------------------------------------------->
<hr>
<A NAME="Zoltan_Print_Sync_Start"></A>
<HR>
void <B>Zoltan_Print_Sync_Start</B>(MPI_Comm <i>communicator</i>,
int <I>do_print_line</I>);&nbsp;
<HR>
<P>The <B>Zoltan_Print_Sync_Start</B> function is adapted from work of John
Shadid for the MPSalsa project at Sandia National Laboratories. With <B><A HREF="#Zoltan_Print_Sync_End">Zoltan_Print_Sync_End</A></B>,
it provides synchronization so that one processor in the Zoltan
communicator can complete its I/O before the next processor begins its
I/O. This synchronization utility is useful for debugging algorithms, as
it allows the output from processors to be produced in an organized manner.
It is, however, a serializing process, and thus, does not scale well to
large number of processors.
<P><B>Zoltan_Print_Sync_Start</B> should called by each processor in the MPI
communicator before the desired I/O is performed. <B><A HREF="#Zoltan_Print_Sync_End">Zoltan_Print_Sync_End</A></B>
is called by each processor after the I/O is performed. No communication
can be performed between calls to <B>Zoltan_Print_Sync_Start</B> and <B><A HREF="#Zoltan_Print_Sync_End">Zoltan_Print_Sync_End</A></B>.
See the <A HREF="#print_sync_example">example</A> below for usage of <B>Zoltan_Print_Sync_Start</B>.
<BR>&nbsp;
<TABLE WIDTH="100%" >
<TR VALIGN=TOP>
<TD VALIGN=TOP WIDTH="20%"><B>Arguments:</B></TD>
<TD WIDTH="80%"></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>communicator</I></TD>
<TD>The MPI communicator containing all processors to participate in the
synchronization.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>do_print_line</I></TD>
<TD>A flag indicating whether to print a line of "#" characters before
and after the synchronization block. If <I>do_print_line</I> is TRUE, a
line is printed; no line is printed otherwise.</TD>
</TR>
</TABLE>
&nbsp;
<P>
<!------------------------------------------------------------------------->
<hr>
<A NAME="Zoltan_Print_Sync_End"></A>
<HR>
void <B>Zoltan_Print_Sync_End</B>(MPI_Comm <i>communicator</i>,
int <I>do_print_line</I>);&nbsp;
<HR>
<P>The <B>Zoltan_Print_Sync_End </B>function is adapted from work of John Shadid
for the MPSalsa project at Sandia National Laboratories. With <B><A HREF="#Zoltan_Print_Sync_Start">Zoltan_Print_Sync_Start</A></B>,
it provides synchronization so that one processor in the Zoltan
communicator can complete its I/O before the next processor begins its
I/O. This synchronization utility is useful for debugging algorithms, as
it allows the output from processors to be produced in an organized manner.
It is, however, a serializing process, and thus, does not scale well to
large number of processors.
<P><B><A HREF="#Zoltan_Print_Sync_Start">Zoltan_Print_Sync_Start</A></B> should
called by each processor in the MPI communicator before the desired I/O
is performed. <B>Zoltan_Print_Sync_End</B> is called by each processor after
the I/O is performed. No communication can be performed between calls to
<B><A HREF="#Zoltan_Print_Sync_Start">Zoltan_Print_Sync_Start</A></B> and <B>Zoltan_Print_Sync_End</B>.
See the <A HREF="#print_sync_example">example</A> below for usage of <B>Zoltan_Print_Sync_End</B>.
<BR>&nbsp;
<TABLE WIDTH="100%" >
<TR VALIGN=TOP>
<TD VALIGN=TOP WIDTH="20%"><B>Arguments:</B></TD>
<TD WIDTH="80%"></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>communicator</I></TD>
<TD>The MPI communicator containing all processors to participate in the
synchronization.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>do_print_line</I></TD>
<TD>A flag indicating whether to print a line of "#" characters before
and after the synchronization block. If <I>do_print_line</I> is TRUE, a
line is printed; no line is printed otherwise.</TD>
</TR>
</TABLE>
<!------------------------------------------------------------------------->
<hr>
<A NAME="Zoltan_Print_Stats"></A>
<HR WIDTH="100%">
void <B>Zoltan_Print_Stats</B>(MPI_Comm <i>comm</i>, int <i>debug_proc</i>,
double <i>x</i>, char <i>*msg</i>);
<BR>
<HR WIDTH="100%">
<BR>Zoltan_Print_Stats is a very simple routine that computes the maximum and
sum of the variable <I>x</I> over all processors associated with the MPI
communicator <i>comm</i>.
It also computes and prints the imbalance
of <I>x</I>, that is, the maximum value divided by the average minus one.
If <I>x </I>has the same value on all processors, the imbalance is zero.
<p>
<TABLE BORDER=0 WIDTH="100%" NOSAVE >
<tr>
<TD VALIGN=TOP WIDTH="20%"><B>Arguments:</B></TD>
<td WIDTH="80%"></td>
</tr>
<TR>
<TD>&nbsp;&nbsp;&nbsp; <I>comm&nbsp;</I></TD>
<TD>The MPI Communicator to be used in maximum and sum operations.
</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;&nbsp; <I>debug_proc&nbsp;</I></TD>
<TD>The processor from which output should be printed.
</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;&nbsp; <I>x</I></TD>
<TD>The variable of which one wishes to display statistics.</TD>
</TR>
<TR NOSAVE>
<TD>&nbsp;&nbsp;&nbsp; <I>msg</I></TD>
<TD NOSAVE>A string that typically describes the meaning of <I>x.</I></TD>
</TR>
</TABLE>
<HR WIDTH="100%">
<H4>
<!------------------------------------------------------------------------->
<HR WIDTH="100%"><A NAME="print_sync_example"></A><B>Example Using Zoltan_Print_Sync_Start/Zoltan_Print_Sync_End</B></H4>
&nbsp;
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR>
<TD><TT>...</TT>&nbsp;
<BR><TT>if (zz->Debug_Level >= ZOLTAN_DEBUG_ALL) {</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp; int i;</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp; Zoltan_Print_Sync_Start(zz->Communicator, TRUE);</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp; printf("Zoltan: Objects to be exported from Proc
%d\n", zz->Proc);</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp; for (i = 0; i &lt; *num_export_objs; i++) {</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; printf("&nbsp;&nbsp;&nbsp;
Obj: ");</tt>
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ZOLTAN_PRINT_GID(zz, &((*export_global_ids)[i*zz->Num_GID]));
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; printf(" Destination: %4d\n",</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(*export_procs)[i]);</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp; }</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp; Zoltan_Print_Sync_End(zz->Communicator, TRUE);</TT>&nbsp;
<BR><TT>}</TT></TD>
</TR>
<CAPTION ALIGN=BOTTOM><I>Example usage of Zoltan_Print_Sync_Start and Zoltan_Print_Sync_End
to synchronize output among processors.&nbsp; (Taken from Zoltan_LB_Partition in
lb/lb_balance.c.)</I></CAPTION>
</TABLE></CENTER>
&nbsp;
<P>
<HR WIDTH="100%">
<BR>[<A HREF="dev.html">Table of Contents</A>&nbsp; |&nbsp; <A HREF="dev_services_objlist.html">Next:&nbsp;
Object List Function</A>&nbsp; |&nbsp; <A HREF="dev_services_params.html">Previous:&nbsp;
Parameter Setting Routines</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

504
thirdParty/Zoltan/docs/dev_html/dev_services_params.html vendored Normal file
View File

@ -0,0 +1,504 @@
<!-------- @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: Parameter Setting Routines</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_services_parallel.html">Next</a>&nbsp; |&nbsp; <a href="dev_services.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->
<h2>
<a NAME="Parameters"></a>Parameter Setting Routines</h2>
Zoltan allows applications to change a number of parameter settings at
runtime. This facility supports debugging by, for instance, allowing control
over the type and quantity of output. It also allows users to modify some
of the parameters that characterize the partitioning algorithms. The design
of the parameter setting routines was driven by several considerations.
First, we wanted to keep the user interface as simple as possible. Second,
we wanted to allow different Zoltan structures to have different
parameter settings associated with them. This second consideration precluded
the use of C's static global variables (except in a few special places).
The parameter routines described below allow developers to provide runtime
access to any appropriate variables. In some cases,
it is appropriate to allow developers to tinker with parameters that will
never be documented for users.
<p>Our solution to parameter setting is to have a single interface routine
<b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
This function calls a set of more domain-specific parameter setting routines,
each of which is responsible for a domain-specific set of parameters. Assuming
there are no errors, the parameter name and new value are placed in a linked
list of new parameters which is maintained by the Zoltan structure.
When a partitioning method is invoked on a Zoltan structure, it
scans through this linked list using the <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>
function, resetting parameter values that are appropriate to the method.
<p>In addition to the method-specific parameters, Zoltan also has a set
of so-called&nbsp;<a NAME="key_params"></a><b>key parameters</b>. These
are normally stored in the Zoltan structure and may be accessed by
any part of the Zoltan code (including all the methods). A list of the
<a href="../ug_html/ug_param.html#General_Parameters">key
parameters currently used in Zoltan</a> can be found in the User's Guide.
<p>The routines that control parameter setting are listed below. Note that
these routines have been written to be as independent of Zoltan as possible.
Only a few minor changes would be required to use these routines as a separate
library.
<blockquote>
<b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b>:&nbsp; User
interface function that calls a set of method-specific routines.
<br><b><a href="#Zoltan_Set_Param_Vec">Zoltan_Set_Param_Vec</a></b>:&nbsp;
Same as Zoltan_Set_Param, but for vector parameters.
<br><b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b>:&nbsp; Routine
to check if parameter name and value are OK.
<br><b><a href="#Zoltan_Bind_Param">Zoltan_Bind_Param</a></b>: Routine to associate a parameter name with a variable.
<br><b><a href="#Zoltan_Bind_Param_Vec">Zoltan_Bind_Param_Vec</a></b>: Same as Zoltan_Bind_Param, but for vector parameters.
<br><b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>:&nbsp;
Scans list of parameter names &amp; values, setting relevant parameters
accordingly.
<br><b><a href="#Zoltan_Free_Params">Zoltan_Free_Params</a></b>: Frees a parameter
list.</blockquote>
See also:&nbsp; <a href="dev_add_params.html">Adding new parameters in
Zoltan</a>.
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Set_Param"></a>
<hr>
int <b>Zoltan_Set_Param</b>(struct <b><a href="dev_lb_structs.html">Zoltan_Struct</a></b>
*<i>zz</i>, char *<i>param_name</i>, char *<i>new_val</i>);
<br>
<hr>
<p>The <b>Zoltan_Set_Param</b> function is the <a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">user
interface for parameter setting</a>. Its principle purpose is to call a
sequence of more domain-specific routines for setting domain-specific parameters
(e.g., <b>Zoltan_RCB_Set_Param</b>). If you are adding algorithms to Zoltan,
you must write one of these domain-specific parameter routines and modify
<b>Zoltan_Set_Param</b>
to call it. <b>Zoltan_RCB_Set_Param</b> can serve as a template for this task.
The arguments to this routine are two strings <i>param_name</i> and <i>new_val</i>.
The domain-specific routines return an integer value with the following
meaning.
<blockquote>0 - The parameter name was found, and the value passed all
error checks.
<br>1 - The parameter name was not found among the parameters known by
the domain-specific routine.
<br>2 - The parameter name was found, but the value failed the error checking.
<br>3 - Same as 0, but do not add parameter and value to linked list.
<br>Other - More serious error; value is an <a href="../ug_html/ug_interface.html#Error Codes">error
code</a>.</blockquote>
If one of the domain-specific parameter routines returns with a 0,
<b>Zoltan_Set_Param</b>
adds the parameter and the value (both strings) to a linked list of such
pairs that is pointed to by the <i>Params</i> field of the <i>zz</i> structure.
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>zz</i></td>
<td>The Zoltan structure whose parameter value is being modified.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>param_name</i></td>
<td>A string containing the name of the parameter being modified. It is
automatically converted to all upper-case letters.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>new_val</i></td>
<td>The new value desired for the parameter, expressed as a string.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>
<td><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Set_Param_Vec"></a>
<hr>
int <b>Zoltan_Set_Param_Vec</b>(struct <b><a href="dev_lb_structs.html">Zoltan_Struct</a></b>
*<i>zz</i>, char *<i>param_name</i>, char *<i>new_val</i>, int <i>index</i>);
<br>
<hr>
<p>
This routine works the same way as <a href="#Zoltan_Set_Param">
Zoltan_Set_Param</a>, but is used for vector parameters.
A vector parameter is a parameter that in
addition to a name also has a set of indices, usually starting at 0. Each entry (component) may have a different value. This routine
sets a single entry (component) of a vector parameter. If you want all entries (components) of a vector parameter to have the
same value, set the parameter using <a href="#Zoltan_Set_Param">
Zoltan_Set_Param</a> as if it were a scalar parameter.
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Check_Param"></a>
<hr>
int <b>Zoltan_Check_Param</b>( char *<i>param_name</i>,
char *<i>new_val</i>, <b>PARAM_VARS</b> *<i>params</i>, <b>PARAM_UTYPE
</b>*<i>result</i>,
int *<i>matched_index</i>);
<br>
<hr>The <b>Zoltan_Check_Param</b> routine simplifies the task of writing your
own domain-specific parameter setting function. <b>Zoltan_Check_Param</b> compares
the <i>param_name</i> string against a list of strings that you provide,
and if a match is found it extracts the new value from the <i>new_val</i>
string. See <b>Zoltan_RCB_Set_Param</b> for an example of how to use this routine.
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>param_name</i></td>
<td>A capitalized string containing the name of the parameter being modified.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>new_val</i></td>
<td>The new value desired for the parameter, expressed as a string.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>params</i></td>
<td>The data structure (defined in <i>params/params_const.h</i>) describing
the domain-specific parameters to be matched against. The data structure
is an array of items, each of which consists of four fields. The first
field is a string that is a capitalized name of a parameter. The second
field is an address that is unused in
<b>Zoltan_Check_Param</b>, but is used
in <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>. The
third field is another capitalized string that indicates the type of the
parameter from the first field. Currently supported types are "INT", "INTEGER",
"FLOAT", "REAL", "DOUBLE", "LONG", "STRING" and "CHAR". It is easy to add additional types
by simple modifications to <b>Zoltan_Check_Param</b> and <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>.
The fourth field is an integer that gives the dimension (length) of
the parameter, if it is a vector parameter. Scalar parameters have dimension 0.
The array is terminated by an item consisting of four NULL fields. See
<b>Zoltan_RCB_Set_Param</b>
for an example of how to set up this data structure.&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>result</i></td>
<td>Structure of information returned by <b>Zoltan_Check_Param</b> (defined
in <i>params/params_const.h</i>).&nbsp; If <i>param_name</i> matches any
of the parameter names from the first field of the <i>params</i> data structure,
<b>Zoltan_Check_Param</b> attempts to decode the value in <i>new_val</i>.
The type of the value is determined by the third field in the <i>params</i>
data structure. If the value decodes properly, it is returned in <i>result</i>.&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>matched_index</i></td>
<td>If <i>param_name</i> matches, then <i>matched_index</i> returns the
index into the <i>params</i> array that corresponds to the matched parameter
name. The <i>matched_index</i> and <i>result</i> values allow the developer
to check that values being assigned to parameters are valid.&nbsp;</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>
<td>0 - <i>param_name</i> found in <i>params</i> data structure and <i>new_val</i>
decodes OK.&nbsp;
<br>1 - <i>param_name</i> not found in <i>params</i> data structure.&nbsp;
<br>2 - <i>param_name</i> found in <i>params</i> data structure but <i>new_val</i>
doesn't decode properly.&nbsp;</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Bind_Param"></a>
<hr WIDTH="100%">
int <b>Zoltan_Bind_Param </b>(<b>PARAM_VARS</b>
*<i>params,</i> char *<i>name,</i> void *<i>var</i>);
<br>
<hr WIDTH="100%">
<br>This routine is used to associate the name of a parameter in the parameter
array <i>params</i> with a variable pointed to by <i>var</i>.
<br>Note that since the variable to be bound can be of an arbitrary type,
the pointer should be cast to a void pointer. <b>Zoltan_Bind_Param</b> must
be called before <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>,
where the actual assignment of values takes place.
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>params</i></td>
<td>The data structure describing the domain-specific parameters to be
matched against. The data structure is an array of items, each of which
consists of four fields. The first field is a string that is a capitalized
name of a parameter. The second field is an address that is unused in
<b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b>,
but is used in <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>.
The third field is another capitalized string that indicates the type
of the parameter from the first field. Currently supported types are "INT",
"INTEGER", "FLOAT", "REAL", "DOUBLE", "LONG", "STRING" and "CHAR".
It is easy to add additional types by simple modifications to <b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b>
and <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>.
The fourth field is an integer that gives the dimension (length) of
the parameter, if it is a vector parameter. Scalar parameters have dimension 0.
The array is terminated by an item consisting of four NULL fields.</td>
</tr>
<tr>
<td>&nbsp;&nbsp; <i>name</i></td>
<td>A capitalized string containing the name of the parameter being modified.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp; <i>var</i></td>
<td NOSAVE>A pointer to the variable&nbsp; you wish to associate with the
parameter name <i>name.</i>&nbsp; The pointer should be type cast to a
void pointer. The user is responsible for ensuring that the pointer really
points to a variable of appropriate type.&nbsp; A NULL pointer may be used
to "unbind" a variable such that it will not be assigned a value upon future
calls to <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a>.</b></td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp; int</td>
<td NOSAVE><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Bind_Param_Vec"></a>
<hr WIDTH="100%">
int <b>Zoltan_Bind_Param_Vec</b>(<b>PARAM_VARS</b>
*<i>params,</i> char *<i>name,</i> void *<i>var</i>, int <i>dim</i>);
<br>
<hr WIDTH="100%">
<p>
Same as Zoltan_Bind_Param, but for vector parameters. The additional
parameter <i>dim</i> gives the dimension or length of the vector parameter.
</p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Assign_Param_Vals"></a>
<hr>
int <b>Zoltan_Assign_Param_Vals</b>(<b>PARAM_LIST</b>
*<i>change_list</i>, <b>PARAM_VARS</b> *<i>params,
</i>int<i> debug_level,</i>
int <i>my_proc,</i> int <i>debug_proc</i>);
<br>
<hr>This routine changes parameter values as specified by the list of names
and new values which is associated with a Zoltan structure. To
use this routine, parameter values should first be set to their defaults,
and then
<b>Zoltan_Assign_Param_Vals</b> should be called to alter the values
as appropriate. See <b>Zoltan_RCB</b> for a template.
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>change_list</i></td>
<td>The linked list of parameter names and values which is constructed
by <b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b> and is a field of an
<b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
data structure (defined in <i>params/param_const.h</i>).&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>params</i></td>
<td>The data structure (defined in <i>params/params_const.h</i>) describing
the domain-specific parameters to be matched against. The data structure
is an array of items, each of which consists of three fields. The first
field is a string which is a capitalized name of a parameter. The second
field is an address of the parameter which should be altered. The third
field is another capitalized string which indicates the type of the parameter
being altered. Currently supported types are "INT", "INTEGER", "FLOAT", "REAL", "DOUBLE",
"LONG", "STRING" and "CHAR". It is easy to add additional types by simple
modifications to <b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b> and
<b>Zoltan_Assign_Param_Vals</b>.
The array is terminated by an item consisting of three NULL fields.&nbsp;</td>
</tr>
<tr>
<td>&nbsp;&nbsp; <i>debug_level</i></td>
<td>Zoltan debug level. (Normally this is <i>zz->Debug_Level</i>.)</td>
</tr>
<tr>
<td>&nbsp;&nbsp; <i>my_proc</i></td>
<td>Processor number. (Normally this is<i> zz->Proc</i>.)</td>
</tr>
<tr>
<td>&nbsp;&nbsp; <i>debug_proc</i></td>
<td>Processor number for debugging. (Normally this is <i>zz->Debug_Proc</i>.)</td>
</tr>
<tr>
<td></td>
<td></td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
<tr>
<td></td>
<td></td>
</tr>
</table>
The last three input parameters may seem strange. They are present to support
Zoltan's debugging features. If the parameter utility code is used outside
of Zoltan, these&nbsp; parameters may be removed or simply set these input
values to zero in the function call.
<p>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<a NAME="Zoltan_Free_Params"></a>
<hr>
void <b>Zoltan_Free_Params </b>(<b>PARAM_LIST</b>
**<i>param_list</i> );
<hr WIDTH="100%">
<br>This routine frees the parameters in the list pointed to by <i>param_list</i>.
<br>&nbsp;
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>param_list</i></td>
<td>A pointer to a list (array) of parameters to be freed.&nbsp; <b>PARAM_LIST</b>
is defined in <i>params/param_const.h</i>.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_services_parallel.html">Next:&nbsp;
Parallel Computing Routines</a>&nbsp; |&nbsp; <a href="dev_services.html">Previous:&nbsp;
Services</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

203
thirdParty/Zoltan/docs/dev_html/dev_services_time.html vendored Normal file
View File

@ -0,0 +1,203 @@
<!-------- @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.76 [en] (X11; U; Linux 2.4.2-2smp i686) [Netscape]">
<meta name="sandia.approved" content="SAND99-1376">
<meta name="author" content="karen devine, kddevin@sandia.gov">
<title> Zoltan Developer's Guide: Timing Routines</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_services_zoltantimer.html">Next</a>&nbsp; |&nbsp; <a href="dev_services_hash.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->
<h2>
<a NAME="Timing"></a>Timing Routines</h2>
To assist in performance measurements and profiling, several timing routines
are included in the Zoltan library. The main timer function,
<b><a href="#Zoltan_Time">Zoltan_Time</a></b>,
provides access to at least two portable timers: one CPU clock and one
wall clock. On most systems, user time can also be measured.
A higher-level timing capability built using
<b><a href="#Zoltan_Time">Zoltan_Time</a></b> is also available; see
<b><a href="dev_services_zoltantimer.html">ZOLTAN_TIMER</a></b> for more
details.
<p>
The routines included in the utility are listed below.
<blockquote><b><a href="#Zoltan_Time">Zoltan_Time</a></b>: Returns the
time (in seconds) after some fixed reference point in time.
<br><b><a href="#Zoltan_Time_Resolution">Zoltan_Time_Resolution</a></b>:&nbsp;
The resolution of the specified timer.</blockquote>
Currently, the following timers are supported:
<ul>
<li>
<i>ZOLTAN_TIME_WALL </i>: wall-clock time.</li>
<br>On most systems, this timer calls MPI_Wtime.
<li>
<i>ZOLTAN_TIME_CPU </i>: cpu time.</li>
<br>On most systems, this timer calls the ANSI C function clock(). Note
that this timer may roll over at just 71 minutes. <b><a href="#Zoltan_Time">Zoltan_Time</a></b>
attempts to keep track of the number of roll-overs but this feature will
work only if <b><a href="#Zoltan_Time">Zoltan_Time</a></b> is called at
least once during every period between roll-overs.
<li>
<i>ZOLTAN_TIME_USER </i>: user time.</li>
<br>On most systems, this timer calls times(). Note that times() is required
by POSIX and is widely available, but it is not required by ANSI C so may
be unavailable on some systems. Compile Zoltan with -DNO_TIMES in this
case.</ul>
Within Zoltan, it is recommended to select which timer to use by setting
the
<a href="../ug_html/ug_param.html#TIMER">TIMER</a> general parameter
via <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
The default value of <a href="../ug_html/ug_param.html#TIMER">TIMER</a>
is <i>wall</i>.&nbsp; Zoltan stores an integer representation of the selected
timing method in <i>zz->Timer</i>. This value should be passed to <b><a href="#Zoltan_Time">Zoltan_Time</a></b>,
as in <b><a href="#Zoltan_Time">Zoltan_Time</a></b>(<i>zz->Timer</i>).
<p><!------------------------------------------------------------------------->
<hr><a NAME="Zoltan_Time"></a>
<hr>double <b>Zoltan_Time</b>(int <i>timer</i>);&nbsp;
<hr>
<p><b>Zoltan_Time</b> returns the time in seconds, measured from some fixed
reference time. Note that the time is <i>not </i>synchronized among different
processors or processes. The time may be either CPU time or wall-clock
time. The timer is selected through <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
<br>&nbsp;
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>timer</i></td>
<td>The timer type (e.g., wall or cpu) represented as an integer. See <a href="#Timing">top
of page</a> for a list of valid values.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; double&nbsp;</td>
<td>The time in seconds. The time is always positive; a negative value
indicates an error.</td>
</tr>
</table>
<p><!------------------------------------------------------------------------->
<hr><a NAME="Zoltan_Time_Resolution"></a>
<hr>double <b>Zoltan_Time_Resolution</b>(int
<i>timer</i>) ;&nbsp;
<hr>
<br><b>Zoltan_Time_Resolution</b> returns the resolution of the current
timer.&nbsp; The returned resolution is a lower bound on the actual resolution.
<br>&nbsp;
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>timer</i></td>
<td>The timer type (e.g., wall or cpu) represented as an integer. See <a href="#Timing">top
of page</a> for a list of valid values.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; double&nbsp;</td>
<td>The timer resolution in seconds.&nbsp; If the resolution is unknown,
-1 is returned.</td>
</tr>
</table>
<br>&nbsp;
<p><!------------------------------------------------------------------------->
<hr><a NAME="Example"></a>
<br><b>Example:</b>
<br>Here is a simple example for how to use the timer routines:
<ul><tt>double t0, t1, t2;</tt>
<br><tt>Zoltan_Set_Param(zz, "TIMER", "wall");</tt>
<br><tt>t0 = Zoltan_Time(zz->Timer);</tt>
<br><tt>/* code segment 1&nbsp; */</tt>
<br><tt>t1 = Zoltan_Time(zz->Timer);</tt>
<br><tt>/* code segment 2&nbsp; */</tt>
<br><tt>t2 = Zoltan_Time(zz->Timer);</tt>
<br><tt>/* Print timing results */</tt>
<br><tt>Zoltan_Print_Stats(zz->Communicator, zz->Debug_Proc, t1-t0, "Time
for part 1:");</tt>
<br><tt>Zoltan_Print_Stats(zz->Communicator, zz->Debug_Proc, t2-t1, "Time
for part 2:");</tt>
<br><tt>Zoltan_Print_Stats(zz->Communicator, zz->Debug_Proc, t2-t0, "Total
time :");</tt></ul>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_services_debug.html">Next:&nbsp;
Debugging Services</a> |&nbsp; <a href="dev_services_hash.html">Previous:&nbsp;
Hash Function</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

1042
thirdParty/Zoltan/docs/dev_html/dev_services_zoltantimer.html vendored Normal file
View File

File diff suppressed because it is too large Load Diff

229
thirdParty/Zoltan/docs/dev_html/dev_test_script.html vendored Normal file
View File

@ -0,0 +1,229 @@
<!-------- @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: Running test_zoltan</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_rcb.html">Next</a>&nbsp; |&nbsp; <a href="dev_view.html">Previous</a></i></b></div>
<h2>
<a NAME="migration_help"></a>Appendix:&nbsp; Using the test script <i>test_zoltan</i></h2>
<B>
Note: The script <i>test_zoltan</i> as described below is obsolete.
It will work in some instances, but is no longer generally supported.
<p>
Automated testing is now supported through CMake. Build
<a href="../ug_html/ug_usage.html#CMake">Zoltan
through CMake</a> with option
<blockquote>
"-D Zoltan_ENABLE_Tests:BOOL=ON"
</blockquote>
<p>
Automated tests can be then run with command
<blockquote>
make test
</blockquote>
The testing environment uses script <i>zoltan/test/ctest_zoltan.pl</i>.
To add new <i>zdrive.inp</i> files to an existing test, add the files to
the appropriate directory and to the glob commands in <i>ctest_zoltan.pl</i>.
(Follow the example of <i>zdrive.inp.rcb</i> in <i>ctest_zoltan.pl</i>.
<p>
To add new test directories, create the directories and populate them
with input files. Copy file <i>CMakeLists.txt</i>
from <i>zoltan/test/ch_simple</i> to the new directories,
and edit the test names and numbers of processors in the new files.
Also add the new directories to <i>zoltan/test/CMakeLists.txt</i>, following
the example of <i>ch_simple</i>. The new tests will now be run in the CMake
environment.
<p>
<a href="https://trilinos.sandia.gov/cdash/index.php?project=Trilinos&subproject=Zoltan">Results of automated nightly testing</a> are posted to the CDASH
dashboard.
</B>
<hr>
<hr>
<B>OBSOLETE</B>
<p>
The purpose of the Zoltan test script is to run the test driver <i><a href="dev_driver.html">zdrive</a></i> (or
<i><a href="dev_driver.html">zfdrive</a></i>)
on a set of test problems to verify that the Zoltan library works correctly.
The script compares the output of actual runs with precomputed output.
The assumption is that if the outputs are identical, then the current implementation
is is likely to be correct.
Small differences may occur depending on the architectures used; developers
should examine the output and use their judgement in determining its correctness.
It is strongly recommended that developers
run <i>test_zoltan</i> to verify correctness before committing changes
to existing code!
<br>&nbsp;
<h3>
How to run <i>test_zoltan</i></h3>
First make sure you have compiled the driver <i><a href="dev_driver.html">zdrive</a></i> (or <i><a href="dev_driver.html">zfdrive</a></i>).&nbsp;
Then go to the Zoltan directory <i>Zoltan/tests</i> and type<i> test_zoltan </i>
with suitable options as described below. This will run the test script
in interactive mode. The output from the driver will be sent to <i>stdout</i>
and <i>stderr</i<i>stdout</i>
and <i>stderr</i>
with a summary of results. The summary of results is also saved in a log
file. If&nbsp; an error occured, look at the log file to find out what
went wrong. The script currently assumes that runs are deterministic
and reproducible across all architectures,
which is not necessarily true.
Hence false alarms may occur.
<br>&nbsp;
<h3>
Syntax</h3>
<b>&nbsp;&nbsp;&nbsp;&nbsp; test_zoltan </b>[-arch <i>arch-type</i>] [-cmd
<i>command</i>]
[other options as listed below]
<p>It is required to use either the -arch or the -cmd option.&nbsp; The
other arguments are optional.
<p>
<table BORDER=0 WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td WIDTH="25%"><b>Options:</b></td>
<td WIDTH="75%"></td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td WIDTH="25%" NOSAVE>-arch <i>arch-type</i></td>
<td WIDTH="75%" NOSAVE>The architecture on which the driver is to run. For a
list of currently supported architectures, type <i>test_zoltan</i> with no
arguments.
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>-cmd <i>command</i></td>
<td>The <i>command</i> is the command that the script
uses to launch the driver. One must include an option to specify the number
of processors as part of the command. Use quotes appropriately; for example,
<i>-cmd
'mpirun -np'</i>. Default settings have been provided for all the supported
architectures.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>-logfile <i>filename</i></td>
<td NOSAVE>The name of the log file. The default is <i>test_zoltan.log</i>.
If an old log file exists, it will be moved to <i>test_zoltan.log.old.</i></td>
</tr>
<tr>
<td>-no_parmetis</td>
<td>Do not run any <a href="../ug_html/ug_alg_parmetis.html">ParMETIS</a>
methods.</td>
</tr>
<tr>
<td>-no_nemesis</td>
<td>Do not run test problems in Nemesis format.</td>
</tr>
<tr>
<td>-no_chaco</td>
<td>Do not run test problems
in <a href="http://cs.sandia.gov/CRF/chac.html">Chaco</a> format.</td>
</tr>
<tr>
<td>-yes_fortran</td>
<td>Run the Fortran90 driver <a href="dev_driver.html"><i>zfdrive</i></a>
instead of <i>zdrive</i>.</td>
</tr>
</table>
<p>The default behavior is to run
<a href="dev_driver.html"><i>zdrive</i></a>
all methods on all types of input format.
<br>&nbsp;
<h3>
Test problems</h3>
The test problems are included in subdirectories of the <i>Zoltan/test</i>
directory. Problems using <a href="http://cs.sandia.gov/CRF/chac.html">Chaco</a> input files are in subdirectories
<i>ch_*</i>; problems using Nemesis input files are in subdirectories
<i>nem_*</i>.
Please see the README files located in each test directory for more
details on these test problems.
<h3>
Load balancing methods</h3>
Many different load-balancing methods are currently tested in <i>test_zoltan</i>.
Input files for the methods are found in the test problem subdirectories.
The input files are named <i>zdrive.inp.&lt;method&gt;</i>, where <i>&lt;method&gt;</i> indicates which load-balancing method is passed to Zoltan.
To run only a subset of the methods,
edit the <i>test_zoltan</i> script manually; searching for "rcb" shows
which lines of the script must be changed.
<br>&nbsp;
<h3>
<b>Number of processors</b></h3>
The script <i>test_zoltan</i> runs each test problem on a predetermined number of processors, currently
ranging from 3 to 9.
<p>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_rcb.html">Next:
RCB</a>&nbsp; |&nbsp; <a href="dev_view.html">Previous:&nbsp; Visualization of Geometric Partitions</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

241
thirdParty/Zoltan/docs/dev_html/dev_view.html vendored Normal file
View File

@ -0,0 +1,241 @@
<!-------- @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="lee ann fisk, lafisk@sandia.gov">
<title> Zoltan Developer's Guide: Visualization of Geometric Partitions</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_test_script.html">Next</a>&nbsp; |&nbsp; <a href="dev_driver.html">Previous</a></i></b></div>
<h2>
<a NAME="Visualization"></a>Appendix: Visualization of Geometric Partitions
</h2>
Graphical images of partitioned meshes can help you to understand the
geometric partitioning algorithms of Zoltan and to debug new or existing
algorithms. The following sections describe methods for visualizing the
partitions computed by the <a href="dev_driver.html">test drivers</a>.
<h3>
<a NAME="Vis_2D"></a>2D problems with <I>gnuplot</I>
</h3>
To view the result of a 2D decomposition performed by the
<a href="dev_driver.html">test driver</a>,
use the "gnuplot output" option of the test driver input file,
as described in <i><a href="zdrive.inp">zdrive.inp</a></i>. The test driver
will write a file that can be loaded into <a href="https://www.gnuplot.info/">gnuplot</a>.
The result for the test mesh in directory <I>ch_hammond</I>, partitioned into four
regions with RCB, is show below. The first picture is obtained from the input file
<i> zdrive.inp.gnuplot1</i> with <i>gnuplot output = 1</i>. The second
picture is obtained from the input file <i> zdrive.inp.gnuplot2</i>
with <i>gnuplot output = 2</i>. Both pictures have been zoomed so
that the xrange is [-0.2,1.2] and the yrange is [-0.3,0.35].
<p>
<img src="hammondPoints.png" alt="[gnuplot 2D view]" border=2 height=488 width=654>
<p>
<p>
<img src="hammondMesh.png" alt="[gnuplot 2D view]" border=2 height=488 width=654>
<p>
<h3>
<a NAME="Vis_3D"></a>3D problems with <I>vtk_view</I>
</h3>
3D visualization requires downloading and compiling the
<a href="https://www.vtk.org">Visualization Toolkit</a> (VTK) library (version
5.0 or later). You can then use the Zoltan top level makefile to build
the <I>vtk_view</I> application found in the <I>util</I> directory of
Zoltan. Build details can be found in the <I>Config.generic</I> file
in <I>Utilities/Config</I>. Note that you will have to download and
build <a href = "https://www.cmake.org">CMake</a>, the makefile generator
used by <a href="https://www.vtk.org">VTK</a>, before you can build VTK.
<p>
<I>vtk_view</I> is a parallel MPI program. It does not need to be
run with the same number of processes with which you ran <I>zdrive</I>. You
can choose the number of processes based on the size of the input mesh you
will be visualizing, and the computational load of rendering it to an image
at interactive rates.
<p>
If you run <I>vtk_view</I> in the directory in which you ran
the test driver, the following will happen:
<UL>
<LI><I>vtk_view</I> will read <I><a href="zdrive.inp">zdrive.inp</a></I>, or another input parameter file
if you specify a different file on the command line.
<LI>It will read in the same input Chaco or Exodus II mesh that the test driver
read in.
<LI>It will read in the <i>file_name</i>.out.<i>p</i>.<i>n</i> files that the
test driver wrote listing the part assigned to every global ID.
<LI>It will open a window on your display, showing the input mesh. For
Chaco files, the mesh vertices will be colored by the part into which
Zoltan placed them. For Exodus II files, the mesh elements will be so colored.
A scalar bar in the window indicates the mapping from colors to part
numbers. A caption describes the input file name, the decomposition
method, the Zoltan parameter settings, and so on. You can use your mouse
to rotate the volume, pan and zoom in and out.
</UL>
<p>
The example below shows how <I>vtk_view</I> displays the mesh in the test directory
<I>ch_brack2_3</I> after it has been partitioned with HSFC across 5 processes.
<p>
<img src="brack3d.png" alt="[vtk_view 3D view]" border=2 height=466 width=473>
<p>
If no test driver output files are found, <I>vtk_view</I> will
display the mesh without part IDs.
<p>
There are a few additional options that can be added to the test driver
input file, that are specifically for <I>vtk_view</I>.
<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
<TR> <TD>zdrive count = &lt;number&gt;</TD>
<TD>the number of <i>file_name</i>.out.<i>p</i>.<i>n</i> files, also the value of <i>p</i></TD>
<TR> <TD>image height = &lt;number&gt;</TD>
<TD>number of pixels in height of image (default is <I>300</I>)</TD>
<TR> <TD>image width = &lt;number&gt;</TD>
<TD>number of pixels in width of image (<I>300</I>)</TD>
<TR> <TD>omit caption = &lt;1 or 0&gt;</TD>
<TD>do not print default caption in window if "1" (<I>0</I>) </TD>
<TR> <TD>omit scalar bar = &lt;1 or 0&gt;</TD>
<TD>do not print scalar bar in window if "1" (<I>0</I>)</TD>
<TR> <TD>add caption = &lt;text of caption&gt;</TD>
<TD>display indicated text in the window (<I>no caption</I>)</TD>
</TABLE>
<p>
The <I>zdrive count</I> option may be required if you have more than one
set of test driver output files in the directory. Otherwise, <I>vtk_view</I>
will look for files of the form <i>file_name</i>.out.<i>p</i>.<i>n</i> for
any value <i>p</i>. Note that since the window may be resized with the
mouse, you may not need <i>image height</i> and <i>image width</i>
unless you must have a very specific window size. Also note that if you
ran the Fortan test driver <I>zfdrive</I>, you will need to rename the
output files from <i>file_name</i>.<B>f</B>out.<i>p</i>.<i>n</i> to
<i>file_name</i>.out.<i>p</i>.<i>n</i>.
<h3>
<a NAME="Vis_offscreen"></a>Off-screen rendering with <I>vtk_write</I>
</h3>
In some situations it is not possible or not convenient to open a window
on a display. In that case, you can compile <I>util/vtk_view.cpp</I> with the flag
<B>OUTPUT_TO_FILE</B> and it will create a program that renders the image
to a file instead of opening a window on a display. (The Zoltan top level makefile
does exactly this when you use the <I>vtk_write</I> target.)
<p>
Note that while
<I>vtk_view</I> is built with OpenGL and <a href=https://www.vtk.org>VTK</a>,
<I>vtk_write</I> must be built
with <a href = https://www.mesa3d.org>Mesa</a> GL and a version of the
<a href=https://www.vtk.org>VTK</a> libraries that you have compiled with
special Mesa flags and with the Mesa header files. This is because
OpenGL implementations are not
in general capable of off-screen rendering, and Mesa GL is. The
<I>Config.generic</I> file in <I>Utilities/Config</I> describes in
detail how to build Mesa and then VTK for off-screen rendering.
<p>
<I>vtk_write</I> goes through the same steps that <I>vtk_view</I> does,
except at the end it writes one or more image files instead of opening
a window on your display. The images begin with a camera focused on the
mesh, pointing in the direction of the negative Z-axis. The positive
Y-axis is the "up" direction, and we use a right-handed coordinate
system. (So the X-axis is pointing to the right.) The camera can
revolve around the mesh in 1 degree increments.
<p>
The <I>zdrive count</I>, <I>image width</I>, and <I>image height</I>
options listed above also apply to <I>vtk_write</I>. In addition, you
can use these options to govern the output images.
<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
<TR> <TD>output format = &lt;format name&gt;</TD>
<TD>choices are tiff, png, jpeg, ps and bmp (default is <I>tiff</I>)</TD>
<TR> <TD>output name = &lt;file name&gt;</TD>
<TD>base name of image file or files (<I>outfile</I>)</TD>
<TR> <TD>output frame start = &lt;number&gt;</TD>
<TD>first frame, between 0 and 360 (<I>0</I>)</TD>
<TR> <TD>output frame stop = &lt;number&gt;</TD>
<TD>last frame, between 0 and 360 (<I>0</I>)</TD>
<TR> <TD>output frame stride = &lt;number&gt;</TD>
<TD>the difference in degrees from one frame to the next (<I>1</I>)</TD>
<TR> <TD>output view up = &lt;x y z&gt;</TD>
<TD>the direction of "up" as camera points at mesh (<I>0 1 0</I>)</TD>
</TABLE>
<h3>
<a NAME="Vis_other"></a>Other file formats
</h3>
<I>vtk_view</I> was written to post-process <I>zdrive</I> runs, so it
only reads Chaco or Exodus II/Nemesis meshes.
If you are working with a different mesh-based file format, it
is still possible that you could use <I>vtk_view</I> or <I>vtk_write</I>
to view the parts assigned to your mesh by some application using the
Zoltan library. <a href=https://www.vtk.org>VTK</a>
at this point in time has readers for many different file formats. If VTK
has a reader for your format, then
modify the <I>read_mesh</I> function in <I>util/vtk_view.cpp</I> to use that
reader.
<p>
You can then hard-code <I>vtk_view</I> to read your file, or you can
modify <I>read_cmd_file</I> in <I>driver/dr_input.c</I> to accept
a specification of your file type in addition to Chaco and Nemesis. If
you do the latter you can create a <a href="zdrive.inp">zdrive-style
input file</a> in which to specify your file name and other visualization
parameters.
<p>
Finally, you need to create text files listing each global ID you supplied
to Zoltan, followed by the part ID assigned by Zoltan, with only
one global ID/part ID pair per line. Name this
file or files using the conventions used by the
<a href=dev_driver.html>test drivers</a>.
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_test_script.html">Next:&nbsp;
Using the Test Script</a>&nbsp; |&nbsp; <a href="dev_driver.html">Previous:&nbsp;
Using the Test Drivers</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html

BIN
thirdParty/Zoltan/docs/dev_html/figures/arrow.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 992 B

BIN
thirdParty/Zoltan/docs/dev_html/film2d.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

BIN
thirdParty/Zoltan/docs/dev_html/hammondMesh.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

BIN
thirdParty/Zoltan/docs/dev_html/hammondPoints.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

591
thirdParty/Zoltan/docs/dev_html/zdrive.inp vendored Normal file
View File

@ -0,0 +1,591 @@
# @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
##############################################################################
#
# EXAMPLE OF zdrive.inp INPUT FILE FOR zdrive AND zfdrive.
#
##############################################################################
# GENERAL NOTES
#
# 1) Any line beginning with a "#" is considered a comment and will be
# ignored by the file parser.
#
# 2) The order of the lines IS NOT significant.
#
# 3) Any lines that are optional are marked as such in this file. Unless
# otherwise noted a line is required to exist in any input file.
#
# 4) The case of words IS NOT significant, e.g., "file" IS equivalent
# to "FILE" or "File", etc.
#
# 5) The amount of blank space in between words IS significant. Each
# word should only be separated by a single space.
#
# 6) Blank lines are ignored.
#
#
##############################################################################
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Decomposition Method = <method>
#
# This line is used to specify the algorithm that Zoltan will use
# for load balancing. Currently, the following methods that are acceptable:
# rcb - Reverse Coordinate Bisection
# octpart - Octree/Space Filling Curve
# parmetis - ParMETIS graph partitioning
# reftree - Refinement tree partitioning
#
#-----------------------------------------------------------------------------
Decomposition Method = rcb
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Zoltan Parameters = <options>
#
# This line is OPTIONAL. If it is not included, no user-defined parameters
# will be passed to Zoltan.
#
# This line is used to to specify parameter values to overwrite the default
# parameter values used in Zoltan. These parameters will be passed to Zoltan
# through calls to Zoltan_Set_Param(). Parameters are set by entries consisting
# of pairs of strings "<parameter string>=<value string>".
# The <parameter string> should be a string that is recognized by the
# particular load-balancing method being used.
# The parameter entries should be separated by commas.
# When many parameters must be specified, multiple
# "Zoltan Parameters" lines may be included in the input file.
# NOTE: The Fortran90 driver zfdrive can read only one parameter per line.
#-----------------------------------------------------------------------------
Zoltan Parameters = DEBUG_LEVEL=3
Zoltan Parameters = RCB_REUSE=0
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# File Type = <file type><,chaco or Matrix Market options>
#
# This line is OPTIONAL. If it is not included, then it is assumed that
# the file type is parallel nemesis.
#
# This line indicates which format the file is in. The current
# file types for this line are:
# NemesisI - parallel ExodusII/NemesisI files (1 per processor)
# Chaco - Chaco graph and/or geometry file(s)
# hypergraph - format documented in driver/dr_hg_readfile.c,
# suffix .hg
# matrixmarket - Matrix Market exchange format, suffix .mtx
# matrixmarket+ - our enhanced Matrix Market format, documented in
# driver/dr_hg_io.c, includes vertex and edge weights,
# and process ownership of matrix data for
# a distributed matrix, suffix .mtxp
#
# For NemesisI input, the initial distribution of data is given in the
# Nemesis files. For Chaco input, however, an initial decomposition is
# imposed by the zdrive. Four initial distribution methods are provided.
# The method to be used can be specified in the chaco options:
# initial distribution = <option>
# where <option> is
# linear -- gives the first n/p objects to proc 0, the
# next n/p objects to proc 1, etc.
# cyclic -- assigns the objects to processors as one would
# deal cards; i.e., gives the first object to proc 0,
# the second object to proc 1, ..., the pth object to
# proc (p-1),the (p+1)th object to proc 0, the (p+2)th
# object to proc 1, etc.
# file -- reads an initial distribution from the input file
# <filename>.assign, where File Name is specified by
# the "File Name" command line below.
# owner -- for vertices, same as "linear." For hyperedge, send a
# copy of a hyperedge to each processor owning one of its
# vertices. (Multiple processors may then store each
# hyperedge.)
# If an initial distribution is not specified, the default is linear.
#
# A second Chaco option is to distribute the objects over a subset
# of the processors, not all processors. The syntax for this is:
# initial procs = k
# where k is an integer between 1 and the number of processors.
# The objects will be evenly distributed among the k first
# processors, using the distribution method optionally specified by
# the "initial distribution" option.
#
# Example:
# File Type = chaco, initial distribution = cyclic, initial procs = 2
# will give proc 0 objects 1, 3, 5, ... and proc 1 objects 2, 4, 6, ...
# while procs 2 and higher get no objects.
#
# For hypergraph, matrixmarket and matrixmarket+ files, there are three
# options that determine how zdrive divides the hypergraph or matrix data
# across the processes initially. (The Zoltan library will redistribute
# these elements yet again before the parallel hypergraph methods begins.)
#
# initial_distribution = {val} initial vertex (object) distribution
#
# linear (default) - First n/p vertices supplied by first process,
# next n/p vertices supplied by next process, and so on.
# cyclic - Deal out the vertex ownership in round robin fashion.
# file - Use process vertex assignment found in the file (.mtxp only)
#
# initial_pins = {val} initial pin (matrix non-zero) distribution
#
# row (default) - Each zdrive process supplies entire rows of the matrix,
# in compressed row storage format
# column - Each zdrive process supplies entire columns of the matrix, in
# compressed column storage format
# linear - First n/p pins (matrix non-zeroes) supplied by first process,
# next n/p pins supplied by next process, and so on.
# cyclic - Deal out the pin ownership in round robin fashion.
# file - Use process pin assignment found in the file (.mtxp only)
# zero - Process zero initially has all pins
#
# initial_procs = {n}
# This has the same meaning that it has for Chaco files. The initial
# vertices, pins and weights are all provided by only {n} processes.
#
# objects = {val} how the file is viewed (define the vertices)
#
# rows - Vertices are the row of the matrix
# columns (default) - Vertices are the columns of the matrix
# nonzeros - Vertices are the nonzeros of the matrix
# NOTE: matrixmarket+ driver only support "columns"
# NOTE: The Fortran90 driver zfdrive does not read NemesisI files.
# NOTE: The Fortran90 driver zfdrive does not accept any Chaco options.
#-----------------------------------------------------------------------------
File Type = NemesisI
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Compression = <type of compression>
#
# This line is OPTIONAL. If it is not included, then it is assumed that
# the input file is not compressed.
# Currently, we support compression for Chaco, hypergraph and matrixmarket file
# format.
#
# This line indicates which compression is used for the file. The current
# compression supported for this line are:
# uncompressed - No compression
# gzip - input file is gzipped. The name should be postfixed by
# the ".gz" extension. example: foo.mtx.gz for original
# file foo in matrix market format.
# NOTE: however, if the corresponding compressed file is not found, the driver try
# to open the file with the "usual" name.
Compression = uncompressed
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# File Name = <filename>
#
# This line contains the filename for the input finite element mesh.
#
# If the file type is NemesisI then this name refers to the base name
# of the parallel ExodusII files that contain the results. The base
# name is the parallel filename without the trailing .<# proc>.<file #>
# on it. This file must contain the Nemesis global information.
#
# If the file type is Chaco, this name refers to the base name of the
# Chaco files containing graph and/or coordinates information. The
# file <filename>.graph will be read for the Chaco graph information;
# The file <filename>.coords will be read for Chaco geometry information.
# The optional file <filename>.assign may be read for an initial decomposition
# by specifying "initial distribution=file" on the "File Type" input line.
# For more information about the format of these files, see
# the Chaco user's guide.
#-----------------------------------------------------------------------------
File Name = testa.par
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Parallel Disk Info = <options>
#
# This line is OPTIONAL. If this line is left blank, then it is assumed
# that there is no parallel disk information, and all of the files are
# in a single directory. This line is used only for Nemesis files.
#
# This line gives all of the information about the parallel file system
# being used. There are a number of options that can be used with it,
# although for most cases only a couple will be needed. The options are:
#
# number=<integer> - this is the number of parallel disks that the
# results files are spread over. This number must
# be specified, and must be first in the options
# list. If zero (0) is specified, then all of the
# files should be in the root directory specified
# below.
# list={list} - OPTIONAL, If the disks are not sequential, then a
# list of disk numbers can be given. This list should
# be enclosed in brackets "{}", and the disk numbers
# can be seperated by any of the following comma,
# blank space, tab, or semicolon.
# offset=<integer> - OPTIONAL, This is the offset from zero that the
# disk numbers begin with. If no number is specified,
# this defaults to 1. This option is ignored if
# "list" is specified.
# zeros - OPTIONAL, This specifies that leading zeros are
# used in the parallel file naming convention. For
# example, on the Paragon, the file name for the
# first pfs disk is "/pfs/tmp/io_01/". If this is
# specified, then the default is not to have leading
# zeros in the path name, such as on the teraflop
# machine "/pfs/tmp_1/".
#
# NOTE: The Fortran90 driver zfdrive ignores this input line.
#-----------------------------------------------------------------------------
Parallel Disk Info = number=4,zeros
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Parallel file location = <options>
#
# This line is OPTIONAL, only if the above line is excluded as well, or
# the number of raids is specified as zero (0). If this line is excluded,
# then the root directory is set to the execution directory, ".", and all
# files should be in that directory. This line is used only for Nemesis
# files.
#
# This line gives all of the information about where the parallel files are
# located. There are only two options for this line, and both must be
# specified. The options are:
# root=<root directory name>
# This line is used to specify what the name of the root directory is
# on the target machine. This can be any valid root directory
# name. For example, if one is running on an SGI workstation and
# using the "tflop" numbering scheme then you could use something
# similar to "/usr/tmp/pio_" in this field so that files would be
# written to root directories named:
# /usr/tmp/pio_1
# /usr/tmp/pio_2
# .
# .
# .
# /usr/tmp/pio_<Parallel Disk Info, number>
#
# subdir=<subdirectory name>
# This line specifies the name of the subdirectory, under the root
# directory, where files are to be written. This is tacked onto
# the end of the "root" after an appropriate integer is added to
# "root". Continuing with the example given for "root", if "subdir"
# had a value of "run1/input" files would be written to directories
# named:
# /usr/tmp/pio_1/run1/input/
# /usr/tmp/pio_1/run1/input/
# .
# .
# .
# /usr/tmp/pio_<Parallel Disk Info, number>/run1/input/
#
# NOTE: The Fortran90 driver zfdrive ignores this input line.
#-----------------------------------------------------------------------------
Parallel File Location = root=/pfs/io_, subdir=mmstjohn
#-----------------------------------------------------------------------------
# Zdrive debug level = <integer>
#
# This line is optional. It sets a debug level within zdrive (not within
# Zoltan) that determines what output is written to stdout at runtime.
# The currently defined values are listed below. For a given debug level
# value i, all debug output for levels <= i is printed.
#
# 0 -- No debug output is produced.
# 1 -- Evaluation of the initial and final partition is done
# through calls to driver_eval and Zoltan_LB_Eval.
# 2 -- Function call traces through major driver functions are
# printed.
# 3 -- Generate output files of initial distribution.
# Debug Chaco input files.
# 4 -- Entire distributed mesh (elements, adjacencies, communication
# maps, etc.) is printed. This output is done serially and can
# be big and slow.
#
# Default value is 1.
#-----------------------------------------------------------------------------
Zdrive debug level = 1
#-----------------------------------------------------------------------------
# text output = <integer>
#
# This line is optional. If the integer specified is greater than zero,
# zdrive produces files listing the part and processor assignment of
# each object. When "text output = 1," P files are generated, where P is
# the number of processors used for the run. Files have suffix ".out.P.N",
# where P is the number of processors and N = 0,...,P-1 is the processor that
# generated the particular file.
#
# Default value is 1.
#-----------------------------------------------------------------------------
text output = 1
#-----------------------------------------------------------------------------
# gnuplot output = <integer>
#
# This line is optional. If the integer specified is greater than zero,
# zdrive produces files that can be plotted using gnuplot. If the integer is
# one, only the vertices of the graph are outputted. If the integer is
# greater than 1, edges are also outputted. Each processor generates
# files containing its decomposition; these files are named similarly
# to the standard output filenames generated by zdrive but they include
# a "gnu" field. A file containing the gnuplot commands to actually
# plot the decomposition is also generated; this file has a ".gnuload" suffix.
# To plot the results, start gnuplot; then type
# load "filename.gnuload"
#
# The decomposition can be based on processor assignment or part
# assignment. See zdrive input line "plot partition".
#
# For Chaco input files, edges are not drawn between neighboring subdomains (
# as Chaco input is balanced with respect to graph nodes). Data style
# "linespoints" is used; this style can be changed using gnuplot's
# "set data style ..." command.
#
# In addition, processor assignments are written to the parallel Nemesis files
# to be viewed by other graphics packages (avs, mustafa, blot, etc.). Note
# that the parallel Nemesis files must have space allocated for at least one
# elemental variable; this allocation is done by nem_spread.
#
# Gnuplot capability currently works only for 2D problems.
#
# Default value is 0.
#-----------------------------------------------------------------------------
gnuplot output = 0
#-----------------------------------------------------------------------------
# nemesis output = <integer>
#
# This line is optional. If the integer specified is greater than zero,
# zdrive writes subdomain assignment information to parallel nemesis files.
# These files match the input nemesis file names, but contain a ".blot" suffix.
# The SEACAS utility nem_join can combine these files into a single Exodus file
# for plotting by blot, avs, mustafa, etc. Note that the input parallel
# Nemesis files must have space allocated for at least one
# elemental variable; this allocation is done by nem_spread.
#
# The decomposition can be based on processor assignment or part
# assignment. See zdrive input line "plot partition".
#
# This option does nothing for Chaco input files.
#
# Default value is 0.
#-----------------------------------------------------------------------------
nemesis output = 0
#-----------------------------------------------------------------------------
# plot partition = <integer>
#
# This line is optional. If the integer specified is greater than zero,
# zdrive writes part assignments to the gnuplot or nemesis output files;
# one file per part is generated.
# Otherwise, zdrive writes processor assignments to the gnuplot or nemesis
# output files, with one file per processor generated.
#
# See zdrive input lines "gnuplot output" and "nemesis output".
#
# Default value is 0 (processor assignments written).
#-----------------------------------------------------------------------------
plot partition = 0
#-----------------------------------------------------------------------------
# print mesh info file = <integer>
#
# This line is optional. If the integer specified is greater than zero,
# zdrive produces files describing the mesh connectivity. Each processor
# generates a file containing its vertices (with coordinates) and elements
# (with vertex connectivity); these files are named
# similarly to the standard output filenames generated by zdrive but they
# include a ".mesh" suffix.
#
# Default value is 0.
#-----------------------------------------------------------------------------
print mesh info file = 0
#-----------------------------------------------------------------------------
# Chaco input assignment inverse = <integer>
#
# This line is optional. It sets the IN_ASSIGN_INV flag, indicating that
# the "inverse" Chaco assignment format should be used if a Chaco assignment
# file is read for the initial decomposition. If this flag is 0, the assignment
# file lists, for each vertex, the processor to which it is assigned. If this
# flag is 1, the assignment file includes, for each processor, the number of
# vertices assigned to the processor followed by a list of those vertices.
# See the Chaco User's guide for a more detailed description of this parameter.
#
# Default value is 0.
#-----------------------------------------------------------------------------
Chaco input assignment inverse = 0
#-----------------------------------------------------------------------------
# Number of Iterations = <integer>
#
# This line is optional. It indicates the number of time the load-balancing
# method should be run on the input data. The original input data is passed
# to the method for each invocation.
# Multiple iterations are useful primarily for testing the RCB_REUSE parameter.
#
# Default value is 1.
#
# NOTE: The Fortran90 driver zfdrive ignores this input line.
#-----------------------------------------------------------------------------
Number of Iterations = 1
#-----------------------------------------------------------------------------
# zdrive action = <integer>
#
# This line is optional. It indicates the action the driver should take,
# typically load-balancing or ordering. Valid values are:
#
# 0 -- No action.
# 1 -- Load balance.
# 2 -- Order.
# 3 -- First load balance, then order.
#
# Default value is 1 (load balance).
#
# NOTE: The Fortran90 driver zfdrive ignores this input line.
#-----------------------------------------------------------------------------
zdrive action = 1
#-----------------------------------------------------------------------------
# Test Drops = <integer>
#
# This line signals that zdrive should exercise the box- and point-assign
# capability of Zoltan. Note that the partitioning method must support
# box- and point-drop, and appropriate parameters (e.g., Keep_Cuts) must also
# be passed to Zoltan; otherwise, an error is returned from the box- and
# point-assign functions.
#
# Default value is 0.
#
# NOTE: The Fortran90 driver zfdrive ignores this input line.
#-----------------------------------------------------------------------------
Test Drops = 0
#-----------------------------------------------------------------------------
# Test DDirectory = <integer>
#
# This line signals that zdrive should exercise the Distributed Directory
# utility of Zoltan. Comparisons between zdrive-generated communication maps
# and DDirectory-generated communication maps are done. If a difference is
# found, a diagnostic message containing "DDirectory Test" is printed as
# output from zdrive.
#
# Default value is 0.
#
# NOTE: The Fortran90 driver zfdrive ignores this input line.
#-----------------------------------------------------------------------------
Test DDirectory = 0
#-----------------------------------------------------------------------------
# Test Null Import Lists = <integer>
#
# This line signals that zdrive should test Zoltan's capability to accept
# NULL import lists to Zoltan_Help_Migrate. It allows the driver to pass NULL
# import lists. This flag's value should not affect the output of zdrive.
#
# Default value is 0.
#
# NOTE: The Fortran90 driver zfdrive ignores this input line.
#-----------------------------------------------------------------------------
Test Null Import Lists = 0
#-----------------------------------------------------------------------------
# Test Multi Callbacks = <integer>
#
# This line signals that zdrive should test the list-based (MULTI) callback
# functions. If this line is set to 1, zdrive registers list-based callback
# functions. Otherwise, callbacks on individual functions are registered.
# This flag's value should not affect the output of zdrive.
#
# Default value is 0.
#-----------------------------------------------------------------------------
Test Multi Callbacks = 0
#-----------------------------------------------------------------------------
# Test Local Partitions = <integer>
#
# This line signals that zdrive should test Zoltan using various values
# of the NUM_LOCAL_PARTS parameter and/or nonuniform part sizes.
# While setting NUM_LOCAL_PARTS using a "Zoltan Parameter" above
# would make all processors have the same number of local parts,
# this flag allows different processors to have different values for
# NUM_LOCAL_PARTS.
# Valid values are integers from 0 to 7.
# 0: NUM_LOCAL_PARTS is not set (unless specified as a
# "Zoltan Parameter" above).
# 1: Each processor sets NUM_LOCAL_PARTS to its processor number;
# e.g., processor 0 requests zero local parts; processor 1
# requests 1 local part, etc.
# 2: Each odd-numbered processor sets NUM_LOCAL_PARTS to its
# processor number; even-numbered processors do not set
# NUM_LOCAL_PARTS.
# 3: One part per proc, but variable part sizes.
# Only set part sizes for upper half of procs
# (using Zoltan_LB_Set_Part_Sizes and global part numbers).
# 4: Variable number of parts per proc, and variable
# part sizes. Proc i requests i parts, each
# of size 1/i.
# 5: One part per proc, but variable part sizes.
# Same as case 3, except all sizes are increased by one to
# avoid possible zero-sized parts.
# 6: One part per proc, but variable part sizes.
# When nprocs >= 6, zero-sized parts on processors >= 2.
# (This case is of particular interest for HSFC.)
# 7: One part per proc, but variable part sizes.
# When nprocs >= 6, zero-sized parts on processors <= 3.
# (This case is of particular interest for HSFC.)
#
# Default value is 0.
#-----------------------------------------------------------------------------
Test Local Partitions = 0
#-----------------------------------------------------------------------------
# Test Generate Files = <integer>
#
# This line signals that zdrive should test Zoltan using Zoltan_Generate_Files
# to produce output files that describe the geometry, graph, or hypergraph
# used in the load-balancing. Such files may be useful for debugging.
#
# 0: Do not generate files.
# 1: Generate files.
#
# Default value is 0.
#-----------------------------------------------------------------------------
Test Generate Files = 0