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/ug_html/Structural_MATVEC_Avg_Time.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 75 KiB

BIN
thirdParty/Zoltan/docs/ug_html/figures/HGFigure.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
thirdParty/Zoltan/docs/ug_html/figures/Z.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.4 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 992 B

131
thirdParty/Zoltan/docs/ug_html/figures/hierexample.fig vendored Normal file
View File

@ -0,0 +1,131 @@
#FIG 3.2
Landscape
Center
Inches
Letter
100.00
Single
-2
1200 2
0 32 #ffffe2
0 33 #f1ecff
0 34 #c4ffff
0 35 #e4ffe2
6 2850 1275 9300 2025
2 2 0 2 16 34 150 0 20 0.000 0 0 -1 0 0 5
2875 1350 9275 1350 9275 1950 2875 1950 2875 1350
4 0 16 100 0 18 24 0.0000 4 285 1485 5400 1800 Network\001
-6
6 825 2625 5325 4575
6 3150 2775 3975 3900
6 3150 2775 3975 3600
1 3 0 2 13 35 110 0 20 0.000 1 0.0000 3547 3172 382 382 3547 3172 3929 3172
4 0 13 100 0 18 18 0.0000 4 210 735 3187 3277 CPU2\001
-6
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
3525 3525 3450 3825
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
3375 3525 3300 3825
-6
6 2100 2775 2925 3900
6 2100 2775 2925 3600
1 3 0 2 19 30 110 0 20 0.000 1 0.0000 2528 3172 382 382 2528 3172 2910 3172
4 0 19 100 0 18 18 0.0000 4 210 735 2168 3277 CPU1\001
-6
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
2550 3525 2700 3825
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
2700 3525 2850 3825
-6
6 4125 2775 4950 3900
6 4125 2775 4950 3600
1 3 0 2 26 32 110 0 20 0.000 1 0.0000 4522 3172 382 382 4522 3172 4904 3172
4 0 26 100 0 18 18 0.0000 4 210 735 4162 3277 CPU3\001
-6
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
4500 3525 4425 3825
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
4350 3525 4275 3825
-6
6 1350 3750 4725 4425
2 2 0 2 10 34 100 0 20 0.000 0 0 -1 0 0 5
1400 3825 4675 3825 4675 4350 1400 4350 1400 3825
4 0 10 50 0 18 18 0.0000 4 270 1050 2550 4200 Memory\001
-6
6 1125 2775 1950 3900
6 1125 2775 1950 3600
1 3 0 2 22 33 110 0 20 0.000 1 0.0000 1553 3172 382 382 1553 3172 1935 3172
4 0 22 100 0 18 18 0.0000 4 210 735 1193 3277 CPU0\001
-6
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
1575 3525 1725 3825
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
1725 3525 1875 3825
-6
2 4 0 2 10 34 150 0 20 0.000 0 0 7 0 0 5
5275 4500 875 4500 875 2700 5275 2700 5275 4500
-6
6 6975 2625 11475 4575
6 9300 2775 10125 3900
6 9300 2775 10125 3600
1 3 0 2 13 35 110 0 20 0.000 1 0.0000 9697 3172 382 382 9697 3172 10079 3172
4 0 13 100 0 18 18 0.0000 4 210 735 9337 3277 CPU2\001
-6
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
9675 3525 9600 3825
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
9525 3525 9450 3825
-6
6 8250 2775 9075 3900
6 8250 2775 9075 3600
1 3 0 2 19 30 110 0 20 0.000 1 0.0000 8678 3172 382 382 8678 3172 9060 3172
4 0 19 100 0 18 18 0.0000 4 210 735 8318 3277 CPU1\001
-6
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
8700 3525 8850 3825
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
8850 3525 9000 3825
-6
6 10275 2775 11100 3900
6 10275 2775 11100 3600
1 3 0 2 26 32 110 0 20 0.000 1 0.0000 10672 3172 382 382 10672 3172 11054 3172
4 0 26 100 0 18 18 0.0000 4 210 735 10312 3277 CPU3\001
-6
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
10650 3525 10575 3825
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
10500 3525 10425 3825
-6
6 7275 2775 8100 3900
6 7275 2775 8100 3600
1 3 0 2 22 33 110 0 20 0.000 1 0.0000 7703 3172 382 382 7703 3172 8085 3172
4 0 22 100 0 18 18 0.0000 4 210 735 7343 3277 CPU0\001
-6
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
7725 3525 7875 3825
2 1 0 2 10 7 100 0 -1 0.000 0 0 -1 0 0 2
7875 3525 8025 3825
-6
6 7500 3750 10875 4425
2 2 0 2 10 34 100 0 20 0.000 0 0 -1 0 0 5
7550 3825 10825 3825 10825 4350 7550 4350 7550 3825
4 0 10 50 0 18 18 0.0000 4 270 1050 8700 4200 Memory\001
-6
2 4 0 2 10 34 150 0 20 0.000 0 0 7 0 0 5
11425 4500 7025 4500 7025 2700 11425 2700 11425 4500
-6
2 1 0 2 0 7 100 0 -1 0.000 0 0 -1 0 0 4
3600 1950 3600 2325 3000 2325 3000 2700
2 1 0 2 0 7 100 0 -1 0.000 0 0 -1 0 0 4
8475 1950 8475 2325 9075 2325 9075 2700
2 1 0 2 0 7 100 0 -1 0.000 0 0 -1 0 0 4
6150 1950 6150 2325 6450 2325 6450 2700
2 1 0 2 0 7 100 0 -1 0.000 0 0 -1 0 0 4
6075 1950 6075 2325 5775 2325 5775 2700
4 1 9 100 0 18 18 0.0000 4 210 960 2325 2625 Node 0\001
4 1 9 100 0 18 36 0.0000 4 75 450 6150 3600 ...\001
4 1 9 100 0 18 18 0.0000 4 210 960 9675 2625 Node 3\001
4 0 17 50 -1 2 24 0.0000 4 330 4095 12000 1575 16 processes compute one\001
4 0 17 50 -1 2 24 0.0000 4 330 4485 12000 1950 4-way ParMetis partitioning\001
4 0 9 50 -1 2 24 0.0000 4 330 4050 11925 3375 Each SMP independently\001
4 0 9 50 -1 2 24 0.0000 4 330 5295 11925 3750 computes 4-way RIB partitioning\001

BIN
thirdParty/Zoltan/docs/ug_html/figures/hierexample.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.9 KiB

548
thirdParty/Zoltan/docs/ug_html/ug.html vendored Normal file
View File

@ -0,0 +1,548 @@
<!-------- @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="ug.html">
<meta name="review" content="28 May, 1999">
<meta name="subject" content="Zoltan User's Guide">
<meta name="sandia.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<meta name="sandia.create_date" content="05/28/99">
<meta name="keywords" content="Zoltan, Zoltan User's Guide, Zoltan dynamic load balancing library, Zoltan parallel computing">
<meta name="description" content="Zoltan: User'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 User'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">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/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-->
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<b><font face="Verdana, Arial, Helvetica"><font size=+2>
User's Guide
</font></font></b>
<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>
<a href="https://www.sandia.gov/~kddevin">Karen Devine</a><br>
Vitus Leung<br>
<a href="https://www.cise.ufl.edu/~srajaman/">Sivasankaran Rajamanickam</a><br>
Lee Ann Riesen<br>
</td>
<td width="50%" valign=top>
<b> Ohio State University</b><br>
<a href="https://bmi.osu.edu/~umit/">Umit Catalyurek</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>
Cedric Chevalier (currently at CEA, DAM, France) <br>
Robert Heaphy<br>
Bruce Hendrickson<br>
Matthew St. John<br>
Courtenay Vaughan<br>
Michael Wolf <br>
<br>
</td>
<td width="50%" valign=top>
<b> Ohio State University</b><br>
<a href="https://www.ece.osu.edu/~bozdagd">Doruk Bozdag</a><br>
</td>
</tr>
<tr>
<td width="50%" valign=top>
<b> Williams College</b><br>
<a href="https://www.teresco.org/~terescoj/">James Teresco</a><br>
<br>
</td>
<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>
</tr>
<tr>
<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 User's Guide, Version 3.8</i></b></div>
<p>
<h4>
<!----------- KDDKDD: Lost ability to generate PDF when Sandia disabled Acrobat. Hope to restore soon.
<table border="1"> <tr> <td>
<a href="http://cs.sandia.gov/Zoltan/Zoltan_pdf/ug.pdf">DOWNLOAD PDF VERSION HERE.</a>
</td> </tr> </table>
------>
<p>
<h4>
<a href="ug_intro.html">Introduction</a></h4>
<blockquote>
<a href="ug_intro.html#Motivation">Project Motivation</a>
<br><a href="ug_intro.html#Tools">The Zoltan Toolkit</a>
<br><a href="ug_intro.html#Terms">Terminology</a>
<br><a href="ug_intro.html#Design">Zoltan Design</a>
</blockquote>
<h4>
<a href="ug_usage.html">Using the Zoltan Library</a></h4>
<blockquote>
<a href="ug_usage.html#System Requirements">System Requirements</a>
<br><a href="ug_usage.html#Building the Library">Building the Library</a>
<br><a href="ug_usage.html#Testing the Library">Testing the Library</a>
<br><a href="ug_usage.html#ReportingBugs">Reporting Zoltan Bugs</a>
<br><a href="ug_usage.html#Incorporating Zoltan">Incorporating Zoltan into Applications</a>
<br><a href="ug_usage.html#Building Applications">Building Applications</a>
<br><a href="ug_usage.html#Data Types for Object IDs">Data Types for Object IDs</a>
<br><a href="ug_cpp.html">C++ Interface</a>
<br><a href="ug_fortran.html">FORTRAN Interface</a>
</blockquote>
<h4>
<a href="ug_interface.html">Zoltan Interface Functions</a></h4>
<blockquote><a href="ug_interface.html#Error Codes">Error Codes</a>
<br><a href="ug_interface_init.html">General Zoltan Interface Functions</a>
<br><a href="ug_interface_lb.html">Load-Balancing Functions</a>
<br><a href="ug_interface_augment.html">Functions for Adding Items to a
Decomposition</a>
<br><a href="ug_interface_mig.html">Migration Functions</a>
<br><a href="ug_interface_order.html">Ordering Functions</a>
<br><a href="ug_interface_color.html">Coloring Functions</a></blockquote>
<h4>
<a href="ug_query.html">Application-Registered Query Functions</a></h4>
<blockquote>
<a href="ug_query_lb.html">General Zoltan Query Functions</a>
<br><a href="ug_query_mig.html">Migration Query Functions</a>
</blockquote>
<h4>
<a href="ug_param.html">Zoltan Parameters and Output Levels</a></h4>
<blockquote>
<a href="ug_param.html#General_Parameters">General Parameters</a>
<br><a href="ug_param.html#Debug Levels in Zoltan">Debugging Levels</a>
</blockquote>
<h4>
<a href="ug_alg.html">Load-Balancing Algorithms and Parameters</a></h4>
<blockquote>
<a href="ug_alg.html#LB Parameters">Load-Balancing Parameters</a>
<br><a href="ug_alg_simple.html">Simple Partitioners for Testing</a>
<blockquote>
<a href="ug_alg_block.html">Block Partitioning </a>
<br><a href="ug_alg_cyclic.html">Cyclic Partitioning </a>
<br><a href="ug_alg_random.html">Random Partitioning </a>
</blockquote>
<a href="ug_alg_geom.html">Geometric (Coordinate-based) Partitioners</a>
<blockquote>
<a href="ug_alg_rcb.html">Recursive Coordinate Bisection (RCB)</a>
<br><a href="ug_alg_rib.html">Recursive Inertial Bisection (RIB)</a>
<br><a href="ug_alg_hsfc.html">Hilbert Space-Filling Curve (HSFC) Partitioning</a>
<br><a href="ug_alg_reftree.html">Refinement Tree Based Partitioning</a>
<!----------
<br><a href="ug_alg_oct.html">Octree/Space-Filling Curve (SFC) Partitioning</a>
----------->
</blockquote>
<a href="ug_alg_hypergraph.html">Hypergraph Partitioning, Repartitioning and Refinement</a>
<blockquote>
<a href="ug_alg_phg.html">PHG</a>
<br><a href="ug_alg_patoh.html">PaToH</a>
</blockquote>
<a href="ug_alg_graph.html">Graph Partitioning and Repartitioning</a>
<blockquote>
<a href="ug_graph_vs_hg.html">Discussion of graph partitioning vs. hypergraph partitioning</a>
<br><a href="ug_alg_phg.html">PHG</a>
<br><a href="ug_alg_parmetis.html">ParMETIS</a>
<br><a href="ug_alg_ptscotch.html">Scotch</a>
</blockquote>
<br><a href="ug_alg_hier.html">Hierarchical Partitioning</a>
<blockquote>
<a href="ug_alg_hier.html#HierMC">For multicore architectures</a>
<br><a href="ug_alg_hier.html#HierDist">For distributed systems</a>
</blockquote>
</blockquote>
<h4>
<a href="ug_order.html">Ordering Algorithms</a></h4>
<blockquote>
<a href="ug_order_parmetis.html">Nested Dissection by METIS/ParMETIS</a>
<br><a href="ug_order_ptscotch.html">Nested Dissection by Scotch</a>
</blockquote>
<h4>
<a href="ug_color.html">Coloring Algorithms</a></h4>
<blockquote>
<a href="ug_color_parallel.html">Parallel Coloring</a>
</blockquote>
<h4>
<a href="ug_util.html">Data Services and Utilities</a></h4>
<blockquote>
<a href="ug_util.html#Building Utilities">Building Utilities</a>
<br><a href="ug_util_mem.html">Dynamic Memory Management</a>
<br><a href="ug_util_comm.html">Unstructured Communication</a>
<br><a href="ug_util_dd.html">Distributed Data Directories</a>
</blockquote>
<h4>
<a href="ug_examples.html">Examples of Library Usage</a></h4>
<blockquote><a href="ug_examples_init.html">General Usage</a>
<br><a href="ug_examples_lb.html">Load-Balancing</a>
<br><a href="ug_examples_mig.html">Migration</a>
<br><a href="ug_examples_query.html">Query Functions</a></blockquote>
<h4>
<a href="ug_release.html">Zoltan Release Notes</a></h4>
<h4>
<a href="ug_backward.html">Backward Compatibility with Earlier Versions of Zoltan</a></h4>
<h4>
<a href="ug_refs.html">References</a></h4>
<h4>
<a href="ug_index.html">Index of Interface and Query Functions</a></h4>
<hr WIDTH="100%">
Copyright (c) 2000-2012, Sandia National Laboratories. <br>
<hr WIDTH="100%">[<a href="../Zoltan.html">Zoltan Home Page</a>&nbsp; |
<a href="ug_intro.html">Next:&nbsp;
Introduction</a>]&nbsp;<!---------MAIN CONTENT AREA ENDS HERE---------><!-- CHANGE CONTACT + E-MAIL, NOTE "SUBJECT" IN E-MAIL CODE --></td>
</tr>
</table>
<!--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>

327
thirdParty/Zoltan/docs/ug_html/ug_alg.html vendored Normal file
View File

@ -0,0 +1,327 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Load-Balancing Algorithms and Parameters</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_simple.html">Next</a>&nbsp; |&nbsp; <a href="ug_param.html">Previous</a></i></b></div>
<!---------------------------------------------------------------------------->
<h2>
<a NAME="Algorithms"></a>Load-Balancing Algorithms and Parameters</h2>
The following dynamic load-balancing algorithms are currently included
in the Zoltan library:
<blockquote>
<br><a href="ug_alg_simple.html">Simple Partitioners for Testing</a>
<blockquote>
<a href="ug_alg_block.html">Block Partitioning (BLOCK)</a>
<br><a href="ug_alg_cyclic.html">Cyclic Partitioning (CYCLIC)</a>
<br><a href="ug_alg_random.html">Random Partitioning (RANDOM)</a>
</blockquote>
<a href="ug_alg_geom.html">Geometric (Coordinate-based) Partitioners</a>
<blockquote>
<a href="ug_alg_rcb.html">Recursive Coordinate Bisection (RCB)</a>
<br><a href="ug_alg_rib.html">Recursive Inertial Bisection (RIB)</a>
<br><a href="ug_alg_hsfc.html">Hilbert Space-Filling Curve Partitioning (HSFC)</a>
<br><a href="ug_alg_reftree.html">Refinement Tree Based Partitioning (REFTREE)</a>
<!----------
<br><a href="ug_alg_oct.html">Octree/Space-Filling Curve (SFC) Partitioning (OCT)</a>
----------->
</blockquote>
<a href="ug_alg_hypergraph.html">Hypergraph Partitioning, Repartitioning and Refinement (HYPERGRAPH)</a>
<blockquote>
<a href="ug_alg_phg.html">PHG</a>
<br><a href="ug_alg_patoh.html">PaToH</a>
</blockquote>
<a href="ug_alg_graph.html">Graph Partitioning and Repartitioning (GRAPH)</a>
<blockquote>
<a href="ug_alg_phg.html">PHG</a>
<br><a href="ug_alg_parmetis.html">ParMETIS</a>
<br><a href="ug_alg_ptscotch.html">Scotch</a>
</blockquote>
<a href="ug_alg_hier.html">Hybrid Hierarchical Partitioning (HIER)</a>
</blockquote>
The parenthetical string is the parameter value for <i><a href="#LB_METHOD">LB_METHOD</a></i>
parameter; the parameter is set through a call to <b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
<p>For further analysis and discussion of some of the algorithms, see [<a href="ug_refs.html#hendrickson-devine">Hendrickson
and Devine</a>].
<p><!---------------------------------------------------------------------------->
<h3>
<a NAME="LB Parameters"></a>
<hr><b>Load-Balancing Parameters</b></h3>
While the overall behavior of Zoltan is controlled by <a href="ug_param.html">general
Zoltan parameters</a>, the behavior of each load-balancing method is controlled
by parameters specific to partitioning which are also set by calls to <b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
Many of these parameters are specific to individual partitioning algorithms,
and are listed in the descriptions of the individual algorithms.&nbsp;
However, several have meaning across multiple partitioning algorithms.
These load-balancing parameters are described below. Unless indicated otherwise,
these parameters apply to both <b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
and
<b><a href="ug_interface_lb.html#Zoltan_LB_Balance">Zoltan_LB_Balance</a></b>.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td VALIGN=TOP><b>Parameters:</b></td>
<td></td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="LB_METHOD"></a>&nbsp;&nbsp;&nbsp; <i>LB_METHOD</i></td>
<td>The load-balancing algorithm used by Zoltan is specified by this parameter.
Valid values are&nbsp;
<blockquote>
BLOCK (for <a href="ug_alg_block.html">block partitioning</a>),
<br>RANDOM (for <a href="ug_alg_random.html">random partitioning</a>),
<br>RCB (for <a href="ug_alg_rcb.html">recursive coordinate bisection</a>),
<br>RIB (for <a href="ug_alg_rib.html">recursive inertial bisection</a>),
<br>HSFC (for <a href="ug_alg_hsfc.html">Hilbert space-filling curve
partitioning</a>),
<br>REFTREE (for <a href="ug_alg_reftree.html">refinement tree based
partitioning</a>)
<br>GRAPH (to choose from collection of methods for <a href=ug_alg_graph.html>graphs</a>),
<br>HYPERGRAPH (to choose from a collection of methods for <a href=ug_alg_hypergraph.html>hypergraphs</a>),
<!--------------
<br>OCTPART (for <a href="ug_alg_oct.html">octree partitioning</a>),
---------------->
<br>HIER (for hybrid <a href="ug_alg_hier.html">hierarchical partitioning</a>)
<br>NONE (for no load balancing).</blockquote>
</td>
</tr>
<tr>
<td style="vertical-align: top;"><span style="font-style: italic;">&nbsp;&nbsp;&nbsp; <a name="LB_APPROACH"></a>LB_APPROACH</span><br>
</td>
<td style="vertical-align: top;">The desired load balancing
approach.
Only <i>LB_METHOD</i> = <a href="ug_alg_hypergraph.html">HYPERGRAPH</a> or
<a href="ug_alg_graph.html">GRAPH</a>
uses the <i>LB_APPROACH</i> parameter. Valid values are
<blockquote>
PARTITION (Partition "from scratch," not taking
into account the current data distribution; this option is recommended
for static load balancing.)<br>
REPARTITION (Partition but take into account current data
distribution to keep data migration low; this option is recommended for
dynamic load balancing.)<br>
REFINE (Quickly improve the current data
distribution.)<br>
</blockquote>
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="NUM_GLOBAL_PARTS"></a>&nbsp;&nbsp;&nbsp; <i>NUM_GLOBAL_PARTS</i></td>
<td>The total number of parts to be generated by a call to <b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>.
Integer values greater than zero are accepted. Not valid for
<b><a href="ug_interface_lb.html#Zoltan_LB_Balance">Zoltan_LB_Balance</a></b>.&nbsp;</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="NUM_LOCAL_PARTS"></a>&nbsp;&nbsp;&nbsp; <i>NUM_LOCAL_PARTS</i></td>
<td>The number of parts to be generated on this processor by a call
to <b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>.
Integer values greater than or equal to zero are accepted. Not valid for <b><a href="ug_interface_lb.html#Zoltan_LB_Balance">Zoltan_LB_Balance</a></b>.&nbsp;
If any processor sets this parameter, NUM_LOCAL_PARTS is assumed to be
zero on processors not setting this parameter.
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="RETURN_LISTS"></a>&nbsp;&nbsp;&nbsp; <i>RETURN_LISTS</i></td>
<td>The lists returned by calls to
<b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
or
<b><a href="ug_interface_lb.html#Zoltan_LB_Balance">Zoltan_LB_Balance</a></b>. Valid values are&nbsp;
<blockquote>
<br>"IMPORT", to return only information about objects to
be imported to a processor
<br>"EXPORT", to return only information about
objects to be exported from a processor
<br>"ALL", or "IMPORT AND EXPORT" (or any string with both "IMPORT"
and "EXPORT" in it) to return both import and export information
<br> "PARTS" (or "PART ASSIGNMENT" or any string with "PART" in it)
to return the new process and part
assignment of every local object, including those not being
exported.
<br>"NONE", to return neither import nor export information
</blockquote>
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="REMAP"></a>&nbsp;&nbsp;&nbsp; <i>REMAP</i></td>
<td>Within
<b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
or
<b><a href="ug_interface_lb.html#Zoltan_LB_Balance">Zoltan_LB_Balance</a></b>,
renumber parts to maximize overlap between the old decomposition and
the new decomposition (to reduce data movement from old to new decompositions).
Valid values are "0" (no remapping) or "1" (remapping). Part assignments from
<a href="ug_query_lb.html#ZOLTAN_PART_MULTI_FN">ZOLTAN_PART_MULTI_FN</a> or
<a href="ug_query_lb.html#ZOLTAN_PART_FN">ZOLTAN_PART_FN</a> query functions
can be used in remapping if provided; otherwise, processor numbers are used
as part numbers. Requests for remapping
are ignored when, in the new decomposition, a part is spread across
multiple processors or part sizes are specified using <a href="ug_interface_lb.html#Zoltan_LB_Set_Part_Sizes"><b>Zoltan_LB_Set_Part_Sizes</b>.</a></td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="IMBALANCE_TOL"></a>&nbsp;&nbsp;&nbsp; <i>IMBALANCE_TOL</i></td>
<td>The amount of load imbalance the partitioning algorithm should deem
acceptable. The load on each processor is computed as the sum of the weights
of objects it is assigned. The imbalance is then computed as the maximum
load divided by the average load. An value for <i>IMBALANCE_TOL</i> of
1.2 indicates that 20% imbalance is OK; that is, the maximum over the average
shouldn't exceed 1.2.&nbsp;</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="MIGRATE_ONLY_PROC_CHANGES"></a>&nbsp;&nbsp;&nbsp; <i>MIGRATE_ONLY_PROC_CHANGES</i></td>
<td>If this value is set to TRUE (non-zero), Zoltan's migration functions will
migrate only objects moving to new processors. They will not migrate objects
for which only the part number has changed; the objects' processor numbers
must change as well. If this value is set to FALSE (zero), Zoltan's migration
functions will migrate all objects with new part or processor assignments.
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="AUTO_MIGRATE"></a>&nbsp;&nbsp;&nbsp; <i>AUTO_MIGRATE</i></td>
<td>If this value is set to TRUE (non-zero), Zoltan will automatically
perform the data migration during calls to <b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
or
<b><a href="ug_interface_lb.html#Zoltan_LB_Balance">Zoltan_LB_Balance</a></b>.
A full discussion of automatic migration can be found in the description
of the <a href="ug_interface_mig.html">migration interface functions</a>.&nbsp;</td>
</tr>
<tr VALIGN=TOP>
<td VALIGN=TOP><a NAME="Default_Parameter_Values"></a><b>Default Values:</b></td>
<td></td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>LB_METHOD</i> = RCB</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>LB_APPROACH</i> = REPARTITION</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>NUM_GLOBAL_PARTS</i> = Number of processors specified in
<b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>NUM_LOCAL_PARTS</i> = 1</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>RETURN_LISTS</i> = ALL</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>REMAP</i> = 1</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>IMBALANCE_TOL</i> = 1.1</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>MIGRATE_ONLY_PROC_CHANGES</i> = 1</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>AUTO_MIGRATE</i> = FALSE</td>
</tr>
</table>
<p><!---------------------------------------------------------------------------->
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_alg_simple.html">Next:&nbsp;
Simple Partitioners for Testing</a>&nbsp; |&nbsp; <a href="ug_param.html">Previous:&nbsp;
Zoltan Parameters and Output Levels</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

108
thirdParty/Zoltan/docs/ug_html/ug_alg_block.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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: BLOCK</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_cyclic.html">Next</a>&nbsp; |&nbsp; <a
href="ug_alg_simple.html">Previous</a></i></b></div>
<h2>
<a name="BLOCK"></a>Block</h2>
A simple partitioner based on block partitioning of the objects.
It is mainly intended for testing. It uses neither geometry
nor connectivity (graph/hypergraph), so it requires very few query
functions.
The block strategy is as follows: Consider all objects (on all processors) as a linear sequence. Assign the first block of n/num_parts objects to the first part, the next block to the second, and so on. Block is smart enough to generalize this method to handle vertex weights and target part sizes. Only a single weight per object (Obj_Weight_Dim=1) is currently supported.
<br>
&nbsp;
<table width="100%" nosave="">
<tbody>
<tr>
<td valign="top"><b>Method String:</b></td>
<td><b>Block</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td><br>
</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_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
</tbody>
</table>
<p>
<HR WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; |
<a href="ug_alg_cyclic.html">Next:&nbsp; Cyclic</a>
|&nbsp; <a href="ug_alg_simple.html">Previous:&nbsp; Simple Partitioners for Testing</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

106
thirdParty/Zoltan/docs/ug_html/ug_alg_cyclic.html vendored Normal file
View File

@ -0,0 +1,106 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: BLOCK</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_random.html">Next</a>&nbsp; |&nbsp; <a
href="ug_alg_block.html">Previous</a></i></b></div>
<h2>
<a name="CYCLIC"></a>Cyclic</h2>
A simple partitioner based on cyclic (round robin) partitioning of the objects.
It uses neither geometry nor connectivity (graph/hypergraph), so it requires very few query functions. This method currently does not take into account target part sizes nor weights, so the parts may not be balanced in this case!
<br>
Note that the partitioning is cyclic with respect to the local order of objects, and NOT by the global ids.
<br>
&nbsp;
<table width="100%" nosave="">
<tbody>
<tr>
<td valign="top"><b>Method String:</b></td>
<td><b>Cyclic</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td><br>
</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_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
</tbody>
</table>
<p>
<HR WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; |
<a href="ug_alg_random.html">Next:&nbsp; Random</a>
|&nbsp; <a href="ug_alg_block.html">Previous:&nbsp; Block Partitioner</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

105
thirdParty/Zoltan/docs/ug_html/ug_alg_geom.html vendored Normal file
View File

@ -0,0 +1,105 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Geometric (Coordinate-Based) Partitioners</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_rcb.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_random.html">Previous</a></i></b></div>
<h2>
<a name="GEOM"></a>Geometric (Coordinate-based) Partitioners</h2>
Geometric partitioners divide data into parts based on the physical
coordinates of the data. Objects assigned to a single part tend to be
physically close to each other in space. Such partitioners are very useful for
applications that don't have explicit
connectivity information (such as particle methods) or for which geometric
locality is important (such as contact detection).
They are also widely used in adaptive finite
element methods because, in general, they execute very quickly and yield
moderately good partition quality.
<p>
The geometric methods are the easiest non-trivial partitioners to incorporate
into applications, as they require only four callbacks: two returning
<a href="ug_query_lb.html#General Functions">object information</a> and
two returning <a href="ug_query_lb.html#Geometry-based Functions">coordinate
information</a>.
<p>
We group <a href="ug_alg_reftree.html">refinement-tree partitioning</a>
for adaptive mesh refinement applications
into the geometric partitioners because
it uses geometric information to determine an initial ordering for coarse
elements of adaptively refined meshes. The refinement-tree partitioner
also requires <a href="ug_query_lb.html#Tree-based Functions">tree-based
callbacks</a> with connectivity information between
coarse and fine elements in refined meshes.
<blockquote>
<a href="ug_alg_rcb.html">Recursive Coordinate Bisection</a> (RCB)
<br><a href="ug_alg_rib.html">Recursive Inertial Bisection</a> (RIB)
<br><a href="ug_alg_hsfc.html">Hilbert Space-Filling Curve Partitioning</a> (HSFC)
<br><a href="ug_alg_reftree.html">Refinement Tree Based Partitioning</a> (Reftree)
</blockquote>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_alg_rcb.html">Next:&nbsp;
Recursive Coordinate Bisection</a>&nbsp; |&nbsp; <a href="ug_alg_random.html">Previous:&nbsp;
Random Partitioning</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

106
thirdParty/Zoltan/docs/ug_html/ug_alg_graph.html vendored Normal file
View File

@ -0,0 +1,106 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Graph Algorithms</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_graph_vs_hg.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_patoh.html">Previous</a></i></b></div>
Note: See also <a href="ug_alg_hypergraph.html">hypergraph partitioning</a>. <p>
<h2>
<a NAME="Graph"></a>Graph partitioning</h2>
<p>Zoltan performs graph partitioning when the <i>LB_METHOD</i>
parameter is set to GRAPH.
Zoltan provides three packages capable of partitioning a graph. The
package is chosen by setting the GRAPH_PACKAGE parameter.
Two packages (ParMetis and Scotch) are external packages and not
part of Zoltan but accessible via Zoltan. The last package is
PHG, Zoltan's native hypergraph partitioner. PHG will treat
the graph as a regular hypergraph with edge size two.
Since PHG was designed for general hypergraphs, it is usually
slower than graph partitioners but often produces better quality.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP><b>Method String:</b></td>
<td><b>GRAPH</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; GRAPH_PACKAGE</i></td>
<td>The software package to use in partitioning the graph.&nbsp;
<br><i><a href=ug_alg_phg.html>PHG</a> (default)</i>&nbsp;
<br><i><a href=ug_alg_parmetis.html>ParMETIS</a></i>&nbsp;
<br><i><a href=ug_alg_ptscotch.html>Scotch/PT-Scotch</a></i>&nbsp;
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_graph_vs_hg.html">Next:&nbsp;
Graph vs. Hypergraph Partitioning</a>&nbsp; |&nbsp; <a href="ug_alg_patoh.html">Previous:&nbsp;
PaToH Hypergraph Partitioning</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

474
thirdParty/Zoltan/docs/ug_html/ug_alg_hier.html vendored Normal file
View File

@ -0,0 +1,474 @@
<!-------- @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="sandia.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<TITLE>Zoltan User's Guide: Hierarchical Partitioning</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_order.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_ptscotch.html">Previous</a></i></b></div>
<H2>
<A NAME="Hier"></A>Hierarchical Partitioning (HIER)</H2>
Hierarchical partitioning refers to a sequence of partitionings,
where each level in the sequence refines the partitions computed in
the prevous level. Zoltan provides two ways to perform hierarchical
partitioning, one targeted to heterogeneous distributed systems, and
one targeted to machines with multiple multicore processors.
<p>
Partitioning to the hierarchy of a distributed system is described
<a href="#HierDist">below</a>. Employing callbacks to the user at
each level, Zoltan will balance the problem across platforms of
varying capabilities while minimizing communication
along slower links.
<p>
Partitioning an application to run on a multicore machine, where the
multicore nodes are expected to be homogeneous in architecture, is
described in the <a href="#HierMC"> next </a> section. Using a parameter
supplied by the application which describes node topology, Zoltan will partition
the problem to balance computation while minimizing inter-node communication,
and communication between on-node structures.
<H3>
<A NAME="HierMC"></A>Hierarchical Partitioning for multicore machines</H2>
With this method, Zoltan computes partitions that balance computation and
minimize communication costs on multicore architectures.
<p>
Some limitations of this method to note are that Zoltan assumes:
<ul>
<li>Each node (processor) of the multicore machine has the same architecture.
<li>The MPI process ranks are consecutive on the multicore nodes.
</ul>
<p>
In particular, if your parameters imply there are 4 MPI processes on each multicore node, Zoltan will assume that processes 0, 1, 2 and 3 are on the same node. Your system administrator should be able to show you how to ensure that your processes are loaded in this order.
<p>
The results shown below emphasize that the benefit to be gained from levels of
hierarchical partitioning is very dependent on the commmunication patterns
of the problem.
<br>
<br>
<table border=2 >
<tr>
<td>
<img width=90% src=Structural_MATVEC_Avg_Time.jpg alt="matvec timings"> </td>
</tr>
<tr>
<td colspan=2>These results show the runtime for matrix vector multiplication
for some matrices from the <a href=https://www.cise.ufl.edu/research/sparse/matrices/>University of Florida</a> matrix collection.
The tests were run on four nodes of the
<a href=https://www.nersc.gov/users/computational-systems/hopper/>Hopper</a>
machine
at <a href=https://www.nersc.gov>NERSC</a>, a machine composed of dual-socket, dual-die nodes, with each die having 6 cores.
The graphs were first partitioned once across all 96 processes with
<a href=https://www.labri.fr/perso/pelegrin/scotch/>PTScotch</a>. Then, using
hierarchical partitioning with <I>TOPOLOGY="24"</I>, they were partitioned across the nodes first, then the cores. Then with <I>TOPOLOGY="2,12"</I> they were partitioned across the nodes, then across the sockets, then into 12 parts. Finally, with <I>TOPOLOGY="2,2,6"</I> they were partitioned across the nodes, then the sockets, then the dies, and finally partitioned into 6 parts. (Runtime is normalized to the flat partitioning case.)
</td>
</tr>
</table>
<BR>&nbsp;
<TABLE WIDTH="100%" NOSAVE >
<TR>
<TD VALIGN=TOP><B>Method String:</B></TD>
<TD><B>HIER</B></TD>
</TR>
<TR>
<TD><B>Parameters:</B></TD>
<TD></TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; HIER_ASSIST</I></TD>
<TD>Setting this parameter to 1 indicates that the application wishes Zoltan
to perform hierarchcial partitioning for homogeneous multicore nodes, without requiring the application to supply query functions guiding the partitioning.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>TOPOLOGY</I></TD>
<TD>This comma-separated list of integers describes the topology of the multicore node. For example:
<BR>"2,8" may refer to a dual-socket processor where each socket has 8 cores.
<BR>"2,4,6" may refer to a dual-socket, 4-die, 6-core node
<BR>"16" would refer to a 16-core node
</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; HIER_DEBUG_LEVEL</I></TD>
<TD>
0 = no debugging output
<BR>1 = show hierarchy and MPI ranks for each part at each level
<BR>2 = in addition, all processes print status information at each level
</TD>
</TR>
<TR>
<TD VALIGN=TOP><B>Default:</B></TD>
<TD></TD>
</TR>
<TR>
<TD></TD>
<TD><I>HIER_ASSIST</I> = 1 if <I>TOPOLOGY</I> is defined, 0 otherwise</TD>
</TR>
<TR>
<TD></TD>
<TD><I>TOPOLOGY</I> has no default value.</TD>
</TR>
<TR>
<TD></TD>
<TD><I>HIER_DEBUG_LEVEL</I> = 0</TD>
</TR>
<TR>
<TD VALIGN=TOP><B>Required Query Functions:</B></TD>
<TD>There are no query functions required specifically for hierarchical
partitioning to multicore nodes. If the application supplies
<a href=ug_alg_geom.html>geometric query functions</a> then Zoltan will use
<a href=ug_alg_rib.html>RIB</a> partitioning at each level, using whatever
relevant parameters the application has set. If the application supplies
<a href=ug_alg_graph.html>graph query functions</a>, then Zoltan will perform
<a href=ug_alg_graph.html>graph partitioning</a> at each level, again using whatever
relevant graph partitioning parameters the application has set.
</TD>
</TR>
</TABLE>
<H3>
<A NAME="HierDist"></A>Hierarchical Partitioning for distributed computing</H2>
Hierarchical partitioning allows the creation of hybrid partitions,
computed using combinations of other Zoltan procedures.
For hierarchical and heterogeneous systems, different choices may be
appropriate in different parts of the parallel environment. There are
tradeoffs in execution time and partition quality (<I>e.g.</I>, surface
indices/communication volume, interprocess connectivity, strictness of load
balance) and some may be more important than others
in some circumstances. For example, consider a cluster of symmetric
multiprocessor (SMP) nodes connected by Ethernet. A more costly graph
partitioning can be done to partition among the nodes, to minimize
communication across the slow network interface, possibly at the
expense of some computational imbalance. Then, a fast geometric
algorithm can be used to partition independently within each node.<P>
Zoltan's hierarchical balancing, implemented by Jim Teresco (Williams
College) during a 2003-04 visit to Sandia, automates the creation of
hierarchical partitions [<U><A HREF="ug_refs.html#para04">Teresco,
<I>et al.</I></A></U>]. It can be used directly by an application or
be guided by the tree representation of the computational environment
created and maintained by the <A
HREF="https://www.cs.williams.edu/drum/">Dynamic Resource Utilization
Model (DRUM)</A> [<U><A HREF="ug_refs.html#adapt03">Devine, <I>et
al.</I> </A>, <A HREF="ug_refs.html#cluster04">Faik, <I>et
al.</I></A>, <A HREF="ug_refs.html#cise05">Teresco, <I>et
al.</I></A></U>].
<!-- DRUM is a software system that supports automatic
resource-aware partitioning and dynamic load balancing for
heterogeneous, non-dedicated, and hierarchical computing environments.
DRUM dynamically models the computing environment using a tree
structure that encapsulates the capabilities and performance of
communication and processing resources. The tree is populated with
performance data obtained from <I>a priori</I> benchmarks and dynamic
monitoring agents that run concurrently with the application. It is
then used to guide partition-weighted and hierarchical partitioning
and dynamic load balancing. Partition-weighted balancing is available
through <A HREF="ug_drum.html">Zoltan's DRUM interface</A>. --><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 and interfaces with
applications through callback functions. A hierarchical balancing
step begins by building an intermediate structure using these
callbacks. This structure is an augmented version of the graph
structure that Zoltan builds to make use of 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. 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.<P>
Hierarchical partitioning requires three callback functions to specify
the number of levels (<B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_NUM_LEVELS_FN">ZOLTAN_HIER_NUM_LEVELS_FN</A></B>),
which parts each process should compute at each level (<B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_PART_FN">ZOLTAN_HIER_PART_FN</A></B>),
and which method and parameters to be used at each level (<B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_METHOD_FN">ZOLTAN_HIER_METHOD_FN</A></B>).
These are in addition to the callbacks needed to specify objects,
coordinates, and graph edges. This fairly cumbersome interface can be
avoided by using the separately available <A
HREF="https://www.cs.williams.edu/~terescoj/research/zoltanParams/">zoltanParams</A>
library. This allows a file-based description to replace these
callbacks. A more direct interface with DRUM's hierarchical machine
model is also planned, allowing hierarchical balancing parameters to
be set by a graphical configuration tool.<P>
We use a simple example to illustrate the use of the callback
mechanism to specify hierarchical a hierarchical partitioning. In the
figure <a href="#HierFigure">below</a>, a hierarchical computing
environment and a desired hierarchical partitioning is shown.
<p>
<center>
<a NAME="HierFigure"></a>
<img SRC="figures/hierexample.gif" />
</center>
<p>
Assume we start one process for each processor, with the processes of
ranks 0-3 assigned to Node 0, 4-7 to Node 1, 8-11 to Node 2, and 12-15
to Node 3. When hierarchical partitioning is invoked, the following
callbacks will be made, and the following actions should be taken by
the callbacks on each node.
<OL>
<LI>The <B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_NUM_LEVELS_FN">ZOLTAN_HIER_NUM_LEVELS_FN</A></B>
callback is called. All processes should return 2, the number of
levels in the hierarchy.
<LI>The <B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_PART_FN">ZOLTAN_HIER_PART_FN</A></B>
callback is called, with a <B>level</B> parameter equal to 0. This
means the callback should return, on each process, the part
number to be computed at level 0 by that process. Since in our
example, the 16 processes are computing a four-way partition at level
0, processes with ranks 0-3 should return 0, ranks 4-7 should return
1, 8-11 should return 2, and 12-15 should return 3.
<LI>The <B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_METHOD_FN">ZOLTAN_HIER_METHOD_FN</A></B>
callback is called, with a <B>level</B> parameter equal to 0, and the
Zoltan_Struct that has been allocated internally by the hierarchical
partitioning procedure is passed as <B>zz</B>. The callback should
use Zoltan_Set_Param to specify an LB_METHOD and any other parameters
that should be done by the four-way partition across the 16 processes
at level 0. In this case, two calls might be appropriate:
<PRE>
Zoltan_Set_Param(zz, "LB_METHOD", "PARMETIS");
Zoltan_Set_Param(zz, "PARMETIS_METHOD", "PARTKWAY");
</PRE>
At this point, Zoltan's hierarchical balancing procedure can proceed
with the level 0 partition, using ParMetis' PARTKWAY method to
produce a four-way partition across the 16 processes, with part 0
distributed among the processes with ranks 0-3, part 1
distributed among 4-7, part 2 distributed among 8-11, and
part 3 distributed among 12-15.
<LI>The <B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_PART_FN">ZOLTAN_HIER_PART_FN</A></B>
callback is called again, this time with <B>level</B> equal to 1. At
level 1, each group of four processes on the same node is responsible for
computing its own four-way partition. To specify this, processes with
ranks 0, 4, 8, and 12 should return 0, ranks 1, 5, 9, and 13 should
return 1, ranks 2, 6, 10, and 14 should return 2, and ranks 3, 7, 11,
and 15 should return 3. Note that we are specifying four separate four-way
partitions at this level, so each group of four processes on the same
node will have one process computing each part 0, 1, 2, and 3,
for that group.
<LI>The <B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_METHOD_FN">ZOLTAN_HIER_METHOD_FN</A></B>
callback is called again, with <B>level</B> equal to 1, and another
internally-allocated Zoltan_Struct passed as <B>zz</B>. Here, we want
all processes to be computing a partition using recursive inertial
bisection. The following call would be appropriate inside the
callback:
<PRE>
Zoltan_Set_Param(zz, "LB_METHOD", "RIB");
</PRE>
Additional Zoltan_Set_Param calls would be used to specify any
additional procedures. Note that in this case, we are computing four
separate partitions but all with the same LB_METHOD. It would be
allowed to specify different LB_METHODs for each group, but all
processes cooperating on a partition must agree on their LB_METHOD
and other parameters (just like any other Zoltan partitioning).
<P>
At this point, Zoltan's hierarchical balancing procedure can proceed
with the level 1 partition, using four independent recursive inertial
bisections produce the four four-way partitions across the processes on
each node. Since this is the final level, the 16 resulting parts
are returned by the hierarchical balancing procedure to the calling
application.
</OL>
<BR>&nbsp;
<TABLE WIDTH="100%" NOSAVE >
<TR>
<TD VALIGN=TOP><B>Method String:</B></TD>
<TD><B>HIER</B></TD>
</TR>
<TR>
<TD><B>Parameters:</B></TD>
<TD></TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; HIER_CHECKS</I></TD>
<TD>If set to 1, forces "sanity checks" to be performed on the
intermediate structure when it is first created, and after the
partitioning at each level.</TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>HIER_DEBUG_LEVEL</I></TD>
<TD>Amount of output the hierarchical partitioning procedures should
produce.&nbsp;
<BR>0 = no statistics; 1 = hierarchical balancing lists; 2 = all
debugging information.</TD>
</TR>
<TR>
<TD VALIGN=TOP><B>Default:</B></TD>
<TD></TD>
</TR>
<TR>
<TD></TD>
<TD><I>HIER_CHECKS</I> = 0</TD>
</TR>
<TR>
<TD></TD>
<TD><I>HIER_DEBUG_LEVEL</I> = 1</TD>
</TR>
<TR>
<TD VALIGN=TOP><B>Required Query Functions:</B></TD>
<TD></TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</A></B></TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</A></B>
</TD>
</TR>
<TR>
<TD></TD>
<TD><B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_NUM_LEVELS_FN">ZOLTAN_HIER_NUM_LEVELS_FN</A></B>,
<B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_PART_FN">ZOLTAN_HIER_PART_FN</A></B>,
and <B><A
HREF="ug_query_lb.html#ZOLTAN_HIER_METHOD_FN">ZOLTAN_HIER_METHOD_FN</A></B>.
</TD>
</TR>
<tr>
<td valign=top>Only if one of the methods used at some level of hierarchical
partitioning requires geometric information:</td>
<td valign=top><b><a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a></b><br>
<b><a href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b>
or <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>Only if one of the methods used at some level of hierarchical
partitioning requires graph information:</td>
<td NOSAVE>
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_FN</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_FN</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a></b>
</td>
</tr>
</TABLE>
&nbsp;
<P>
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_order.html">Next:&nbsp; Ordering </A>&nbsp;
|&nbsp; <A HREF="ug_alg_ptscotch.html">Previous:&nbsp;&nbsp; PT-Scotch</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

228
thirdParty/Zoltan/docs/ug_html/ug_alg_hsfc.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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: HSFC</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_alg_reftree.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_rib.html">Previous</a></i></b></div>
<h2>
<a NAME="HSFC"></a>Hilbert Space Filling Curve (HSFC)</h2>
The Inverse Hilbert Space-Filling Curve functions map a point in one, two or three dimensions
into the interval [0,1]. The Hilbert functions that map [0, 1] to normal spatial
coordinates are also provided. (The one-dimensional inverse Hilbert curve is defined here
as the identity function, f(x)=x for all x.)
<p>
The HSFC partitioning algorithm seeks to divide [0,1] into P intervals each containing
the same weight of objects associated to these intervals by their inverse Hilbert
coordinates. N bins are created (where N > P) to partition [0,1]. The weights in
each bin are summed across all processors.
A greedy algorithm sums the bins (from left to right) placing a cut when the desired weight
for current part interval is achieved.
This process is repeated as needed to improve partitioning tolerance by
a technique that maintains the same total number of bins but refines the bins previously
containing a cut.
<p>
HSFC returns an warning if the final imbalance exceeds the user specified tolerance.
<p>
This code implements both the point assign and box assign functionality. The point
assign determines an appropriate part (associated with a specific group of processors)
for a new point. The box assign determines the list of processors
whose associated subdomains intersect the given box. In order to
use either of these routines, the user parameter KEEP_CUTS must be turned on.
Both point assign and box assign now work for points or boxes anywhere in space even if
they are exterior to the original bounding box. If a part is empty (due to the
part being assigned zero work), it is not included in the list of parts
returned by box assign. Note: the original box assign algorithm was not rigorous and
may have missed parts. This version is both rigorous and fast.
<p>
The Zoltan implementation of HSFC has one parameter that can be modified
by the <b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
function.
<p>
This partitioning algorithm is loosely based on the 2D & 3D Hilbert tables used in the Octree
partitioner 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. The box assign algorithm is loosely based on the papers by Lawder referenced both
in the developers guide and the code itself. NOTE: This code can be trivially extended to
any space filling curve by providing the tables implementing the curve's state transition
diagram. The only dependance on the curve is through the tables and the box assign
algorithm will work for all space filling curves (if we have their tables.)
<p>
Please refer to the Zoltan Developers Guide,
<b><a href="../dev_html/dev_hsfc.html">Appendix: Hilbert Space Filling Curve (HSFC)</a></b>
for more detailed information about these algorithms.
<br>&nbsp;
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP><b>Method String:</b></td>
<td><b>HSFC</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> KEEP_CUTS</i></td>
<td>Information about cuts and bounding box is necessary
if the application wants to add more objects to the decomposition via calls
to <b><a href="ug_interface_augment.html#Zoltan_LB_Point_PP_Assign">Zoltan_LB_Point_PP_Assign</a></b>
or to <b><a href="ug_interface_augment.html#Zoltan_LB_Box_PP_Assign">Zoltan_LB_Box_PP_Assign</a></b>.&nbsp;
<br>0 = don't keep cuts; 1 = keep cuts.</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> REDUCE_DIMENSIONS</i></td>
<td>
When a 3 dimensional geometry is almost flat, it may make more
sense to treat it as a 2 dimensional geometry when applying the HSFC
algorithm. (Coordinate values in the omitted direction are ignored for the purposes of partitioning.)
If this parameter is set to <B>1</B>, a 3 dimensional
geometry will be treated as 2 dimensional if is very flat,
or 1 dimensional if it very thin. And a 2 dimensional geometry will
be treated as 1 dimensional if it is very thin.
Turning this parameter on removes the possibility that disconnected
parts will appear on the surface of a flat 3 dimensional object.
</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> DEGENERATE_RATIO</i></td>
<td>
If the <B>REDUCE_DIMENSIONS</B> parameter is set, then this parameter
determines when a geometry is considered to be flat.
A bounding box which is oriented to the geometry is constructed, and
the lengths of its sides are tested against a ratio of 1 : <B>DEGENERATE_RATIO</B>.
</td>
</tr>
<tr>
<td VALIGN=TOP><b>Default:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><i>KEEP_CUTS</i> = 0</td>
</tr>
<tr>
<td></td>
<td><i>REDUCE_DIMENSIONS</i> = 0</td>
</tr>
<tr>
<td></td>
<td><i>DEGENERATE_RATIO</i> = 10</td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr>
<td></td>
<td>
<b><a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a></b>
</td>
</tr>
<tr>
<td></td>
<td>
<b><a href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b>
or <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
</td>
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; |
<a href="ug_alg_reftree.html">Next:&nbsp; Refinement Tree Partitioning</a>
|&nbsp; <a href="ug_alg_rib.html">Previous:&nbsp; Recursive Inertial Bisection</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

155
thirdParty/Zoltan/docs/ug_html/ug_alg_hypergraph.html vendored Normal file
View File

@ -0,0 +1,155 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Hypergraph Algorithms</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_phg.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_reftree.html">Previous</a></i></b></div>
<h2>
<a NAME="Hypergraph"></a>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 can be cast as a hypergraph in one of two ways: either every
pair of neighboring vertices form a hyperedge, or a vertex and all
its neighbors form a hyperedge.
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>
<p>
A new feature available in Zoltan 3.0 is the ability to assign selected
objects (vertices) to a particular part ("fixed vertices").
When objects are fixed,
Zoltan will not migrate them out of the user assigned part.
See the descriptions of the
<i><a href="ug_query_lb.html#ZOLTAN_NUM_FIXED_OBJ_FN">ZOLTAN_NUM_FIXED_OBJ_FN</a></i>
and
<i><a href="ug_query_lb.html#ZOLTAN_FIXED_OBJ_LIST_FN">ZOLTAN_FIXED_OBJ_LIST_FN</a></i>
query functions for a discussion of how you can define these two
functions to fix objects to parts. Both PHG and PaToH support this
feature.
<p>
For applications that already use Zoltan to do graph partitioning,
it is easy to upgrade to hypergraph partitioning. For many applications,
the hypergraph model is superior to the graph model, but in some cases
the graph model should be preferred. PHG can also be used as a pure
graph partitioner. See the section
<a href="ug_graph_vs_hg.html">graph vs. hypergraph</a> partitioning
for further details. </p>
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP><b>Method String:</b></td>
<td><b>HYPERGRAPH</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; HYPERGRAPH_PACKAGE</i></td>
<td>The software package to use in partitioning the hypergraph.&nbsp;
<br><i><a href=ug_alg_phg.html>PHG (Zoltan, the default)</a></i>&nbsp;
<br><i><a href=ug_alg_patoh.html>PATOH</a></i>&nbsp;
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_alg_phg.html">Next:&nbsp;
PHG</a>&nbsp; |&nbsp; <a href="ug_alg_reftree.html">Previous:&nbsp;
Refinement Tree Partitioning</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

207
thirdParty/Zoltan/docs/ug_html/ug_alg_jostle.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
------->
<!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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Jostle Interface</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_hier.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_parmetis.html">Previous</a></i></b></div>
<h2>
<a NAME="Jostle"></a>Graph partitioning: Jostle</h2>
<a href="https://staffweb.cms.gre.ac.uk/~c.walshaw/jostle/">Jostle</a> is a library for graph
(mesh) partitioning and load balancing developed at the University of Greenwich,
London, UK, by Chris Walshaw [<a href="ug_refs.html#jostle">Jostle</a>,
<a href="ug_refs.html#walshaw">Walshaw</a>].
The parallel version of Jostle is sometimes called pjostle. In the Zoltan
context, the name Jostle always refers to the parallel version of the library.
The main algorithm used in Jostle is based on multilevel graph partitioning,
and a diffusion-type method is available for repartitioning. Hence the
Jostle library is very similar to ParMETIS. See the <a href="ug_alg_parmetis.html">ParMETIS</a>
section for a brief description of graph partitioning as a model for load
balancing.
<p>At present, only the most common Jostle options are supported by Zoltan.
These are briefly described below. For further details, see the documentation
available from the <a href="https://staffweb.cms.gre.ac.uk/~c.walshaw/jostle/">Jostle home page</a>.
Other options may be added to Zoltan upon request.
<p>Note that Jostle is not distributed with Zoltan. If you wish to use
Jostle within Zoltan, you must first obtain a license for Parallel Jostle
and install it on your system. The license is currently free for academic
use.&nbsp; Zoltan has been tested only with parallel Jostle version
1.2.* and may be incompatible with other versions.
Zoltan offers only limited support for Jostle and this may be
discontinued in the future.
<br>
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP><b>Value of LB_METHOD:</b></td>
<td><b>GRAPH</b></td>
</tr>
<tr>
<td VALIGN=TOP><b>Value of GRAPH_PACKAGE:</b></td>
<td><b>Jostle</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>JOSTLE_OUTPUT_LEVEL</i></td>
<td>Amount of output Jostle should produce.&nbsp; (integer)</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>JOSTLE_THRESHOLD</i></td>
<td>Threshold at which the graph contraction phase is stopped. (integer)</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>JOSTLE_GATHER_THRESHOLD</i></td>
<td>Duplicate coarse graph on all processors when there are fewer than
this number of nodes. (integer)</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>JOSTLE_MATCHING</i></td>
<td>Matching algorithm for graph contraction. (Valid values are "local"
and "global".)</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp;&nbsp; <i>JOSTLE_REDUCTION</i></td>
<td NOSAVE>When reduction is turned off, Jostle performs a diffusion-type
algorithm instead of multilevel graph partitioning. (Valid values are "on"
and "off".)</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>JOSTLE_CONNECT</i></td>
<td>Make a disconnected graph connected before partitioning. (Valid values
are "on" and "off".)</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp;&nbsp; <i>CHECK_GRAPH</i></td>
<td NOSAVE>Level of error checking for graph input: 0 = no checking, 1
= on-processor checking, 2 = full checking. (CHECK_GRAPH==2 is very slow and should
be used only during debugging).</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp;&nbsp; <i>SCATTER_GRAPH</i></td>
<td NOSAVE>Scatter graph data by distributing contiguous chunks of objects
(vertices)&nbsp; of roughly equal size to each processor before calling
the partitioner. 0 = don't scatter; 1 = scatter only if all objects are
on a single processor; 2 = scatter if at least one processor owns no objects;&nbsp;
3 = always scatter.&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP><b>Default values:</b></td>
<td>See the <a href="https://staffweb.cms.gre.ac.uk/~c.walshaw/jostle/">Jostle</a>&nbsp; documentation.&nbsp;
See our <a href="ug_alg_parmetis.html">ParMETIS section </a>for the last
two parameters.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td></td>
<td NOSAVE>
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_FN</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_FN</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a></b>
</td>
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_alg_hier.html">Next:&nbsp;
Hybrid Hierarchical Partitioning</a>&nbsp; |&nbsp; <a href="ug_alg_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>

221
thirdParty/Zoltan/docs/ug_html/ug_alg_oct.html vendored Normal file
View File

@ -0,0 +1,221 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<TITLE>Zoltan User's Guide: Octree Partitioning</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_order.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_patoh.html">Previous</a></i></b></div>
<H2>
<A NAME="Octree"></A>Octree Partitioning (OCTPART)</H2>
The Octree Partitioning algorithm is based upon work in load balancing
for parallel mesh generation at Rensselaer Polytechnic Institute [<A HREF="ug_refs.html#flaherty">Flaherty,
Loy et al.</A>]. It was implemented in Zoltan by Luis Gervasio, Department
of Computer Science, Rensselaer Polytechnic Institute, as his summer project
in 1998 [<A HREF="ug_refs.html#gervasio">Gervasio</A>]. An octree is a spatial
decomposition of the computational domain in which the root of the tree,
representing the entire domain, is recursively divided by two in each coordinate
direction (producing eight or four "child" octants in 3D or 2D, respectively)
until each subregion holds at most an application-specified number of objects.
These subregions are represented by the leaves of the octree. The octree
data structure is widely used in mesh generation and adaptive mesh refinement
[<U><A HREF="ug_refs.html#baehmann">Baehmann et al.</A></U>, <U><A HREF="ug_refs.html#shephard">Shephard
and Georges</A></U>]. The octree resulting from such a spatial decomposition
of the domain can be used to partition an application's work [<A HREF="ug_refs.html#edwards">Edwards</A>,
<A HREF="ug_refs.html#pilkington">Pilkington and Baden</A>, <A HREF="ug_refs.html#warren">Warren
and Salmon</A>]. To partition an octree, a traversal of the tree is used
to define a global ordering on the leaves of the octree. This global ordering
is often referred to as a Space-Filling Curve (SFC). The leaves of the
octree can be easily assigned to processors in a manner which equally distributes
work by assigning slices of the ordered list to processors. Different tree-traversal
algorithms produce different global orderings or SFCs, with some SFCs having
better connectivity and partition quality properties than others. Currently,
Morton Indexing (i.e., Z-curve), Grey Code, and Hilbert SFCs are supported.
Morton Indexing and Grey Code SFCs are the simplest (and currently, the
fastest) of the SFC algorithms, but they produce lower-quality partitions
than the Hilbert SFC.
<BR>&nbsp;
<TABLE WIDTH="100%" NOSAVE >
<TR>
<TD VALIGN=TOP><B>Method String:</B></TD>
<TD><B>OCTPART</B></TD>
</TR>
<TR>
<TD><B>Parameters:</B></TD>
<TD></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>OCT_DIM</I></TD>
<TD>Specifies whether the 2D or 3D Octree algorithms should be used. The
3D algorithms can be used for 2D problems, but much memory will be wasted
to allow for a non-existent third dimension. Similarly, a 2D algorithm
can be used for 3D surface meshes provided that the surface can be projected
to the <I>xy</I>-plane without overlapping points.&nbsp;
<BR>2 = use 2D algorithm; 3 = use 3D algorithm.</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; OCT_METHOD</I></TD>
<TD>The SFC to be used.&nbsp;
<BR>0 = Morton Indexing; 1 = Grey Code; 2 = Hilbert.</TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>OCT_MINOBJECTS</I></TD>
<TD>The minimum number of objects to allow in a leaf octant of the octree.
These objects will be assigned as a group to a processor, so this parameter
helps define the granularity of the load-balancing problem. Values greater than
or equal to one are allowable.</TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>OCT_MAXOBJECTS</I></TD>
<TD>The maximum number of objects to allow in a leaf octant of the octree.
These objects will be assigned as a group to a processor, so this parameter
helps define the granularity of the load-balancing problem. Values greater than
or equal to one are allowable.</TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>OCT_OUTPUT_LEVEL</I></TD>
<TD>Amount of output the load-balancing algorithm should produce.&nbsp;
<BR>0 = no statistics; 1 = statistics summary; 2 = debugging information; 3 = data for generating plots.</TD>
</TR>
<TR>
<TD VALIGN=TOP><B>Default:</B></TD>
<TD></TD>
</TR>
<TR>
<TD></TD>
<TD><I>OCT_DIM</I> = 3</TD>
</TR>
<TR>
<TD></TD>
<TD><I>OCT_METHOD</I> = 2</TD>
</TR>
<TR>
<TD></TD>
<TD><I>OCT_MINOBJECTS</I> = 10</TD>
</TR>
<TR>
<TD></TD>
<TD><I>OCT_MAXOBJECTS</I> = 40</TD>
</TR>
<TR>
<TD></TD>
<TD><I>OCT_OUTPUT_LEVEL</I> = 0</TD>
</TR>
<TR>
<TD VALIGN=TOP><B>Required Query Functions:</B></TD>
<TD></TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</A></B></TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</A></B>
</TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</A></B></TD>
</TR>
<TR>
<TD></TD>
<TD>
<b><a href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b>
or <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
</TD>
</TR>
</TABLE>
&nbsp;
<P>
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_order.html">Next:&nbsp; Ordering </A>&nbsp;
|&nbsp; <A HREF="ug_alg_patoh.html">Previous:&nbsp;&nbsp; ParKway</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

87
thirdParty/Zoltan/docs/ug_html/ug_alg_parkway.html vendored Normal file
View File

@ -0,0 +1,87 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: ParKway</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_oct.html">Next</a>&nbsp; |&nbsp; <a
href="ug_alg_patoh.html">Previous</a></i></b></div>
<h2>
<a name="Parkway"></a>ParKway</h2>
<p>
This is what ParKwaydoes and why you should use it.
</p>
<br>
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP><b>Value of LB_METHOD:</b></td>
<td><b>HYPERGRAPH</b></td>
</tr>
<tr>
<td VALIGN=TOP><b>Value of HYPERGRAPH_PACKAGE:</b></td>
<td><b>PARKWAY</b></td>
</tr>
</table>
<hr width="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a
href="ug_alg_oct.html">Next:&nbsp;
Octree</a>&nbsp; |&nbsp; <a href="ug_alg_patoh.html">Previous:&nbsp;
PaToH</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

438
thirdParty/Zoltan/docs/ug_html/ug_alg_parmetis.html vendored Normal file
View File

@ -0,0 +1,438 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: ParMETIS Interface</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_ptscotch.html">Next</a>&nbsp; |&nbsp; <a
href="ug_graph_vs_hg.html">Previous</a></i></b></div>
<h2>
<a name="ParMETIS"></a>ParMETIS - Parallel Graph Partitioning</h2>
<a href="https://www-users.cs.umn.edu/%7Ekarypis/metis/parmetis/">ParMETIS</a>
is a parallel library for graph partitioning (for static load
balancing)
and repartitioning (for dynamic load balancing) developed at the
University
of Minnesota by Karypis, Schloegel and Kumar [<a
href="ug_refs.html#parmetis">Karypis
and Kumar</a>]. Note that ParMetis must be obtained separately and has a different license than Zoltan (see page 31 of <a
href="https://glaros.dtc.umn.edu/gkhome/fetch/sw/parmetis/manual.pdf">
this manual</a>). ParMETIS is strictly speaking not a method but
rather a collection of methods. In the Zoltan context, ParMETIS is a
method
with many sub-methods. Zoltan provides an interface to all the ParMETIS
(sub-)methods.&nbsp; The user selects which ParMETIS method to use
through
the parameter PARMETIS_METHOD. Most of the ParMETIS methods are based
on
either multilevel Kernighan-Lin partitioning or a diffusion algorithm.
The names of the ParMETIS methods used by Zoltan are identical to those
in the ParMETIS library. For further information about the various <a
href="https://www-users.cs.umn.edu/%7Ekarypis/metis/parmetis/">ParMETIS</a>
methods and parameters, please consult the <a
href="https://www-users.cs.umn.edu/%7Ekarypis/metis/parmetis/">ParMETIS</a>
User's Guide.
<p>Graph partitioning is a useful abstraction for load balancing. The
main
idea is to represent the computational application as a weighted graph.
The nodes or vertices in the graph correspond to objects in
Zoltan.&nbsp;
Each object may have a weight that normally represents the amount of
computation.
The edges or arcs in the graph usually correspond to communication
costs.
In graph partitioning, the problem is to find a partition of the
graph
(that is,&nbsp; each vertex is assigned to one out of <i>k</i>
possible
sets called parts) that minimizes the cut size (weight) subject to
the parts having approximately equal size (weight). In
repartitioning,
it is assumed that a partition already exists. The problem is to
find
a good partition that is also "similar" in some sense to the
existing
partition. This keeps the migration cost low. All the problems
described
above are NP-hard so no efficient exact algorithm is known, but
heuristics work well in practice.<br>
</p>
<p>We give only a brief summary of the various ParMETIS methods here;
for
more details see the <a
href="https://www-users.cs.umn.edu/%7Ekarypis/metis/parmetis/">ParMETIS</a>
documentation. The methods fall into three categories:
</p>
<ol>
<li>
Part* - Perform graph partitioning without consideration of the initial
distribution. (LB_APPROACH=partition)<br>
</li>
<li>
AdaptiveRepart - Incremental
algorithms with small migration cost. (LB_APPROACH=repartition)</li>
<li>
Refine* - Refines a given partition (balance).&nbsp; Can be applied
multiple times to reduce the communication cost (cut weight) if
desired. (LB_APPROACH=refine)</li>
</ol>
As a rule of thumb, use one of the Part* methods if you have a poor
initial
balance and you are willing to spend some time doing migration. One
such
case is static load balancing; that is, you need to balance only once.
Use AdaptiveRepart or the Repart* methods when you have a reasonably
good
load balance that you wish to update incrementally. These methods are
well
suited&nbsp; for dynamic load balancing (for example,&nbsp; adaptive
mesh
refinement). A reasonable strategy is to call PartKway once to obtain a
good initial balance and&nbsp; later update this balance using
AdaptiveRepart.
<p>
Zoltan supports the multiconstraint partitioning
feature of ParMETIS through multiple object weights (see <i><a
href="ug_param.html#General_Parameters">OBJ_WEIGHT_DIM</a></i>).
</p>
<p>The graph given to Zoltan/ParMETIS must be symmetric. Any self edges
(loops) will be ignored. Multiple edges between a pair of vertices is
not allowed. All weights must be non-negative. The graph does not have to
be connected.
</p>
<p>Zoltan is currently compatible with ParMETIS version 3.1 and 4.0.x.
The ParMETIS source code can be obtained from
the <a href="https://glaros.dtc.umn.edu/gkhome/views/metis/parmetis">
ParMETIS home page</a>. ParMETIS has a separate license:
<i>'PARMETIS can be freely used for educational and research purposes by non-profit institutions and US government agencies only. Other organizations are allowed to
use PARMETIS only for evaluation purposes, and any further uses will require prior approval from <a href="https://www.license.umn.edu/Products/ParMETIS---Mesh-Graph-Partitioning-Algorithm__Z09041.aspx">the technology transfer office at the University of Minnesota</a>'
</i> <br>
If you do not wish to install ParMETIS, it
is possible to compile Zoltan without any references to ParMETIS;
(when you 'make' Zoltan, comment out the PARMETIS_LIBPATH variable in
the
configuration file <i><a href="ug_usage.html#Building%20the%20Library">Utilities/Config/Config.&lt;platform&gt;</a></i>).
</p>
<br>
&nbsp;
<table nosave="" width="100%">
<tbody>
<tr>
<td valign="top"><b>Value of LB_METHOD:</b></td>
<td><b>GRAPH</b></td>
</tr>
<tr>
<td valign="top"><b>Value of GRAPH_PACKAGE:</b></td>
<td><b>Parmetis</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td><br>
</td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp;&nbsp; LB_APPROACH<br>
</i></td>
<td>The load balancing approach:. <br>
<i>PARTITION</i>&nbsp; - partition from scratch, not taking
the current data distribution into account<br>
<i>REPARTITION</i>&nbsp; - partition but try to stay close to the
current partition/distribution
<br>
<i>REFINE</i>&nbsp; - refine the current partition/distribution;
assumes only small changes
</td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp;&nbsp; PARMETIS_METHOD</i></td>
<td>The specific ParMETIS method to be used (see below).
Note: See also <a href="ug_alg.html#LB_APPROACH">LB_APPROACH</a>,
which is a simpler way to specify the overall load balance approach.
Only use <i>PARMETIS_METHOD</i> if you really need a specific
implementation.<br>
<i>PartKway</i> - multilevel Kernighan-Lin partitioning&nbsp;
<br>
<i>PartGeom</i> - space filling curves (coordinate based)&nbsp;
<br>
<i>PartGeomKway</i> - hybrid method based on PartKway and
PartGeom
(needs both&nbsp; graph data and coordinates)&nbsp;
<br>
<i>AdaptiveRepart - </i>adaptive repartitioning (only in
ParMETIS 3.0
and higher)
<br>
<i>RefineKway</i> - refine the current partition (balance)</td>
</tr>
<tr>
<td><br>
</td>
<td>The method names are case insensitive.</td>
</tr>
<tr>
<td valign="top">&nbsp;&nbsp;&nbsp; <i>PARMETIS_OUTPUT_LEVEL</i></td>
<td>Amount of output the load-balancing algorithm should
produce.&nbsp;
<br>
0 = no output, 1 = print timing info. Turning on more bits displays
more information (for example, 3=1+2, 5=1+4, 7=1+2+4).</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp; <i>PARMETIS_COARSE_ALG</i></td>
<td>Coarse algorithm for PartKway. 1 = serial, 2 = parallel.
(ParMETIS
2 only)</td>
</tr>
<tr>
<td>&nbsp;&nbsp;&nbsp; <i>PARMETIS_SEED</i></td>
<td>Random seed for ParMETIS.</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>PARMETIS_ITR</i></td>
<td nosave="">Ratio of interprocessor communication time to
redistribution
time. A high value will emphasize reducing the edge cut, while a small
value will try to keep the change in the new partition (distribution)
small.
This parameter is used only by AdaptiveRepart. A value of between 100
and
1000 is good for most problems.</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>CHECK_GRAPH</i></td>
<td nosave="">Level of error checking for graph input: 0 = no
checking, 1
= on-processor checking, 2 = full checking. (CHECK_GRAPH==2 is very
slow
and should be used only during debugging).</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>SCATTER_GRAPH</i></td>
<td nosave="">Scatter graph data by distributing contiguous
chunks of objects
(vertices) of roughly equal size to each processor before calling the
partitioner.
0 = don't scatter;
1 = scatter only if all objects are on a single processor;
2 = scatter if at least one processor owns no objects;
3 = always scatter.&nbsp;</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>GRAPH_SYMMETRIZE</i></td>
<td nosave="">How to symmetrize the graph:
NONE = graph is symmetric and no symmetrization is needed <br/>
TRANSPOSE = if M is adjacency matrix of the input graph, output will be the graph representation of M+M<sup>T</sup> <br/>
BIPARTITE = graph is symmetrized in a bipartite way : [[ 0 M ][M<sup>t</sup> 0]]
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>GRAPH_SYM_WEIGHT</i></td>
<td nosave="">How edge weights are handled during symmetrization:
ADD = weights of each arc are added <br/>
MAX = only the heaviest arc weight is kept <br/>
<p>See more informations about graph build options on this <a href="ug_graph_build.html">page</a></p>
<!-- ERROR = fail if complementary arcs don't have the same weight. -->
</td>
</tr>
<!-- <tr nosave="" valign="top"> -->
<!-- <td>&nbsp;&nbsp;&nbsp; <i>GRAPH_BIPARTITE_TYPE</i></td> -->
<!-- <td nosave=""> In the case of a bipartite symmetrization, -->
<!-- NONE = graph is symmetric and no symmetrization is needed <br/> -->
<!-- TRANSPOSE = if M is adjacency matrix of the input graph, output will be the graph representation of M+M<sup>T</sup> <br/> -->
<!-- BIPARTITE = graph is symmetrized in a bipartite way : [[ 0 M ][M<sup>t</sup> 0]] -->
<!-- </td> -->
<!-- </tr> -->
<tr>
<td valign="top"><b>Default values:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><i>LB_APPROACH</i> = Repartition</td>
</tr>
<tr>
<td><br>
</td>
<td><i>PARMETIS_METHOD</i> = AdaptiveRepart</td>
</tr>
<tr>
<td><br>
</td>
<td><i>PARMETIS_OUTPUT_LEVEL</i> = 0</td>
</tr>
<tr>
<td><br>
</td>
<td><i>PARMETIS_COARSE_ALG </i>= 2</td>
</tr>
<tr>
<td><br>
</td>
<td><i>PARMETIS_SEED </i>= 15</td>
</tr>
<tr>
<td><br>
</td>
<td><i>PARMETIS_ITR </i>= 100</td>
</tr>
<tr>
<td><br>
</td>
<td><i>USE_OBJ_SIZE </i>= 1</td>
</tr>
<tr>
<td><br>
</td>
<td><i>CHECK_GRAPH</i> = 1</td>
</tr>
<tr>
<td><br>
</td>
<td><i>SCATTER_GRAPH </i>= 1</td>
</tr>
<tr>
<td><br>
</td>
<td><i>GRAPH_SYMMETRIZE </i>= NONE</td>
</tr>
<tr>
<td><br>
</td>
<td><i>GRAPH_SYM_WEIGHT </i>= ADD</td>
</tr>
<tr>
<td valign="top"><b>Required Query Functions:</b></td>
<td><br>
</td>
</tr>
<tr>
<td>For all submethods:</td>
<td><b><a href="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_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr>
<td>Only PartGeom &amp; PartGeomKway:</td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td>
<b><a href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b>
or <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
</td>
</tr>
<tr nosave="" valign="top">
<td>All but PartGeom:</td>
<td nosave="">
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_FN</a></b>
or
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_FN</a></b>
or
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_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_query_mig.html#ZOLTAN_OBJ_SIZE_MULTI_FN">ZOLTAN_OBJ_SIZE_MULTI_FN</a></b>
or
<b><a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN</a></b> for <i>PARMETIS_METHOD</i>=<i>AdaptiveRepart</i>
</td>
</tr>
<tr>
<td><br>
</td>
<td>
<b><a href="ug_query_lb.html#ZOLTAN_PART_MULTI_FN">ZOLTAN_PART_MULTI_FN</a></b>
or
<b><a href="ug_query_lb.html#ZOLTAN_PART_FN">ZOLTAN_PART_FN</a></b> for part remapping in ParMETIS.
</td>
</tr>
</tbody>
</table>
</p>
<hr width="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a
href="ug_alg_ptscotch.html">Next:&nbsp;
PT-Scotch</a>&nbsp; |&nbsp; <a href="ug_graph_vs_hg.html">Previous:&nbsp;
Graph vs. Hypergraph Partitioning</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

225
thirdParty/Zoltan/docs/ug_html/ug_alg_patoh.html vendored Normal file
View File

@ -0,0 +1,225 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: PaToH</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_graph.html">Next</a>&nbsp; |&nbsp; <a
href="ug_alg_phg.html">Previous</a></i></b></div>
<h2>
<a name="PaToH"></a>PaToH</h2>
<a href="https://bmi.osu.edu/%7Eumit/software.htm">PaToH</a>
is a serial hypergraph partitioning package. It is not distributed
with Zoltan and must be obtained separately. (You will also need to
modify your Zoltan configuration file after installation.)
PaToH binary distribution is available free of charge for
non-commercial, research use by individuals, academic or research
institutions and corporations. Commercial use of PaToH software
requires commercial license. Please direct commercial-use license
inquiries to catalyurek.1@osu.edu.
<p>
Since PaToH is serial, it can be used in Zoltan only on a single
processor. PaToH is faster than Zoltan PHG in serial mode, and
often produces (slightly) better partition quality.
<p>
<table nosave="" width="100%">
<tbody>
<tr>
<td VALIGN=TOP><b>Value of LB_METHOD:</b></td>
<td><b>HYPERGRAPH</b></td>
</tr>
<tr>
<td VALIGN=TOP><b>Value of HYPERGRAPH_PACKAGE:</b></td>
<td><b>PATOH</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td><br>
</td>
</tr>
<tr>
<td ><i>&nbsp;&nbsp;&nbsp; PATOH_ALLOC_POOL0</i></td>
<td>
<br><i>non-zero</i>&nbsp&nbsp(the value of the MemMul_CellNet PATOH parameter)
<br><i>0</i>&nbsp&nbsp(the default)
</td>
</tr>
<tr>
<td ><i>&nbsp;&nbsp;&nbsp; PATOH_ALLOC_POOL1</i></td>
<td>
<br><i>non-zero</i>&nbsp&nbsp(the value of the MemMul_Pins PATOH parameter)
<br><i>0</i>&nbsp&nbsp(the default)
</td>
</tr>
<tr>
<td ><i>&nbsp;&nbsp;&nbsp; USE_TIMERS</i></td>
<td>
<br><i>1</i>&nbsp&nbsp(time operations and print results)
<br><i>0</i>&nbsp&nbsp(don't time, the default)
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp; <span style="font-style: italic;">PHG_EDGE_SIZE_THRESHOLD</span><br>
</td>
<td nosave="">Value 0.0 through 1.0, if number of vertices in hyperedge divided by total vertices in hypergraph exceeds this fraction, the hyperedge will be omitted.<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp; <span
style="font-style: italic;">ADD_OBJ_WEIGHT</span><br>
</td>
<td style="vertical-align: top;">Add implicit vertex (object)
weight. Multi-weight partitioning is not yet supported, so currently either
the user-defined weight or the implicit weight will be used.
Valid values:<br>
<i>none</i> (the default if <a href=ug_param.html#General_Parameters>OBJ_WEIGHT_DIM</a> > 0)<br>
<i>unit</i> or <i>vertices</i> (each vertex has weight 1.0,
default if <a href=ug_param.html#General_Parameters>OBJ_WEIGHT_DIM</a>
is zero)<br>
<i>pins</i> or <i>nonzeros</i> or <i>vertex degree</i> (vertex weight
equals number hyperedges containing it)<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp;&nbsp; <span
style="font-style: italic;">CHECK_HYPERGRAPH</span><br>
</td>
<td style="vertical-align: top;">Check that the query functions
return valid input data; 0 or 1. (This slows performance; intended for debugging.)<br>
</td>
</tr>
<tr>
<td><b>Default Values:</b></td>
<td><br>
</td>
</tr>
<tr>
<td></td>
<td><i>PATOH_ALLOC_POOL0</i> = 0 </td>
</tr>
<tr>
<td></td>
<td><i>PATOH_ALLOC_POOL1</i> = 0 </td>
</tr>
<tr>
<td></td>
<td><i>USE_TIMERS</i> = 0 </td>
</tr>
<tr>
<td></td>
<td><i>PHG_EDGE_SIZE_THRESHOLD</i> = 0.25 </td>
</tr>
<tr>
<td></td>
<td><i>ADD_OBJ_WEIGHT</i> = none </td>
</tr>
<tr>
<td></td>
<td><i>CHECK_HYPERGRAPH</i> = 0 </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_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr nosave="" valign="top">
<td><br>
</td>
<td nosave=""> <b><a href="ug_query_lb.html#ZOLTAN_HG_SIZE_CS_FN">ZOLTAN_HG_SIZE_CS_FN</a></b>
<br>
<b><a href="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_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_query_lb.html#ZOLTAN_HG_EDGE_WTS_FN">ZOLTAN_HG_EDGE_WTS_FN</a></b></td>
</tr>
</body>
</table>
<hr width="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a
href="ug_alg_graph.html">Next:&nbsp;
Graph Partitioning</a>&nbsp; |&nbsp; <a href="ug_alg_phg.html">Previous:&nbsp;
PHG</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

485
thirdParty/Zoltan/docs/ug_html/ug_alg_phg.html vendored Normal file
View File

@ -0,0 +1,485 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Hypergraph Partitioning</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_patoh.html">Next</a>&nbsp; |&nbsp; <a
href="ug_alg_hypergraph.html">Previous</a></i></b></div>
<h2 =""><a name="PHG"></a>PHG - Parallel Hypergraph and Graph Partitioning with
Zoltan</h2>
This is the built-in parallel hypergraph partitioner in Zoltan.
<p>
<table nosave="" width="100%">
<tbody>
<tr>
<td valign="top"><b>Value of LB_METHOD:</b></td>
<td><b>HYPERGRAPH</b> (for <a href="ug_alg_hypergraph.html">hypergraph</a> partitioning) or <br>
<b>GRAPH</b> (for <a href="ug_alg_graph.html">graph</a> partitioning)
</td>
</tr>
<tr>
<td valign="top"><b>Value of HYPERGRAPH_PACKAGE:</b></td>
<td><b>PHG</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td><br>
</td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp; LB_APPROACH<br>
</i></td>
<td>The load balancing approach:. <br>
<i>REPARTITION</i>&nbsp; - partition but try to stay close to the
current partition/distribution
<br>
<i>REFINE</i>&nbsp; - refine the current partition/distribution;
assumes only small changes
<br>
<i>PARTITION</i>&nbsp; - partition from scratch, not taking&nbsp;
the current data distribution into account<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp; <span
style="font-style: italic;">PHG_REPART_MULTIPLIER</span><br>
</td>
<td style="vertical-align: top;"> For repartitioning, this
parameter determines the trade-off between application communication
(as represented by cut edges) and data migration related to
rebalancing. PHG attempts to minimize the function
(PHG_REPART_MULTIPLIER* edge_cut + migration volume). The migration
volume is measured using the <a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_MULTI_FN">ZOLTAN_OBJ_SIZE_MULTI_FN</a> or <a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN</a> query functions. Make sure the
units for edges and object sizes are the same.<br>
Simply put, to emphasize communication within the application, use a
large value for PHG_REPART_MULTIPLIER. Typically this should be
proportional to the number of iterations between load-balancing calls. </td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp; PHG_MULTILEVEL<br>
</i></td>
<td>This parameter specifies whether a multilevel method
should be used (1) or not (0). Multilevel methods produce higher quality but
require more execution time and memory.
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&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>
<td style="vertical-align: top;">&nbsp;&nbsp; <span
style="font-style: italic;">ADD_OBJ_WEIGHT</span><br>
</td>
<td style="vertical-align: top;"> Add another object (vertex)
weight. Currently multi-weight partitioning is not supported, but this
parameter may also be used for implicit vertex weights. Valid values
are: <br>
<i>NONE</i> <br>
<i>UNIT</i> or <i>VERTICES</i> (each vertex has weight 1.0) <br>
<i>PINS</i> or <i>NONZEROS</i> or <i>vertex degree</i> (vertex
weight equals number of hyperedges containing it, i.e., the degree)<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp; <span
style="font-style: italic;">PHG_CUT_OBJECTIVE</span><br>
</td>
<td style="vertical-align: top;"> Selects the partitioning
objective, <i>CONNECTIVITY</i> or <i>HYPEREDGES</i>. While hyperedges
simply counts the number of hyperedges cut, the connectivity metric
weights each cut edge by the number of participating parts minus one
(aka the &lambda;-1 cut metric). The connectivity metric better represents
communication volume for most applications. The hyperedge metric is
useful for certain applications, e.g., minimizing matrix border size in
block matrix decompositions. <br>
</td>
</tr>
<tr>
<td style="vertical-align: top;"><span style="font-style: italic;">&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; <span
style="font-style: italic;">CHECK_HYPERGRAPH</span><br>
</td>
<td style="vertical-align: top;">Check that the query functions
return valid input data; 0 or 1. (This slows performance; intended for
debugging.)<br>
</td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp; PHG_COARSENING_METHOD</i></td>
<td>Low-level parameter: The method to use in the matching/coarsening phase:<br>
<span style="font-style: italic;">AGG</span> - agglomerative inner product
matching (a.k.a. agglomerative heavy connectivity matching); gives high quality.<br>
<span style="font-style: italic;">IPM</span> - inner product
matching (a.k.a. heavy connectivity matching); gives high quality.<br>
<span style="font-style: italic;">L-IPM </span>-&nbsp; local IPM
on each processor. Faster but usually gives poorer quality. <br>
<span style="font-style: italic;">A-IPM</span> - alternate
between IPM and L-IPM. (A compromise between speed and quality.)<br>
<span style="font-style: italic;">none -&nbsp; </span>no
coarsening<i><br>
</i></td>
</tr>
<tr>
<td valign="top">&nbsp;&nbsp; <i>PHG_COARSEPARTITION_METHOD</i></td>
<td>Low-level parameter: 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
assignment of the vertices (ordered by the user query function)<br>
<span style="font-style: italic;">GREEDY</span> - greedy method
based on minimizing cuts<br>
<span style="font-style: italic;">AUTO</span> -&nbsp;
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; <span
style="font-style: italic;">PHG_REFINEMENT_METHOD</span><br>
</td>
<td style="vertical-align: top;">Low-level parameter: Refinement algorithm:<br>
<span style="font-style: italic;">FM</span> - approximate
Fiduccia-Mattheyses (FM)<br>
<span style="font-style: italic;">NO</span> - no refinement<br>
</td>
</tr>
<tr>
<td valign=top>&nbsp;&nbsp; <i>PHG_REFINEMENT_QUALITY</i></td>
<td>Low-level parameter: Knob to control the trade-off between run time and quality. 1
is the recommended (default) setting, &gt;1 gives more refinement
(higher quality partitions but longer run time), while &lt;1 gives less
refinement (and
poorer quality).<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">&nbsp;&nbsp; <span
style="font-style: italic;">PHG_RANDOMIZE_INPUT</span><br>
</td>
<td style="vertical-align: top;">Low-level parameter: Randomize layout of vertices and
hyperedges in internal parallel 2D layout? <br>
Setting this parameter to 1 often reduces Zoltan-PHG execution time.<br>
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp; <span style="font-style: italic;">PHG_EDGE_SIZE_THRESHOLD</span><br>
</td>
<td nosave="">Low-level parameter: Value 0.0 through 1.0, if number of vertices in
hyperedge divided by total vertices in hypergraph exceeds this
fraction, the hyperedge will be omitted.<br>
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp; <span style="font-style: italic;">PHG_PROCESSOR_REDUCTION_LIMIT</span><br>
</td>
<td nosave="">Low-level parameter: In V-cycle, redistribute coarsened hypergraph to
this
fraction of processors when number of pins in coarsened hypergraph is
less than
this fraction of original number of pins. Original number of pins is
redefined
after each processor redistribution.<br>
</td>
</tr>
<tr>
</tr>
<tr>
<td valign="top"><b>Default values:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><i>LB_APPROACH = REPARTITION<br>
</i></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">PHG_REPART_MULTIPLIER=100</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">PHG_MULTILEVEL=1 if LB_APPROACH = partition or repartition; 0 otherwise.</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;">ADD_OBJ_WEIGHT=none</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">PHG_CUT_OBJECTIVE=connectivity</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">CHECK_HYPERGRAPH=0</span><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><i>PHG_COARSENING_METHOD=agg</i></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><i>PHG_COARSEPARTITION_METHOD=auto</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_QUALITY=1</i></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 style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;"><span style="font-style: italic;">PHG_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;">PHG_PROCESSOR_REDUCTION_LIMIT=0.5</span></td>
</tr>
<tr>
<td valign="top"><b>Required Query Functions for <i>LB_METHOD = HYPERGRAPH</i>:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="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_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr nosave="" valign="top">
<td><br>
</td>
<td nosave=""> <b><a href="ug_query_lb.html#ZOLTAN_HG_SIZE_CS_FN">ZOLTAN_HG_SIZE_CS_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_HG_CS_FN">ZOLTAN_HG_CS_FN</a></b>
</td>
</tr>
<tr>
<td valign="top"><b>Optional Query Functions for <i>LB_METHOD = HYPERGRAPH</i>:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td>
<b><a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_MULTI_FN">ZOLTAN_OBJ_SIZE_MULTI_FN</a></b>
or
<b><a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN</a></b> for <i>LB_APPROACH</i>=<i>Repartition</i>.
</td>
</tr>
<tr>
<td><br>
</td>
<td>
<b><a href="ug_query_lb.html#ZOLTAN_PART_MULTI_FN">ZOLTAN_PART_MULTI_FN</a></b>
or
<b><a href="ug_query_lb.html#ZOLTAN_PART_FN">ZOLTAN_PART_FN</a></b> for <i>LB_APPROACH</i>=<i>Repartition</i> and for <a href="ug_alg.html#REMAP"><i>REMAP</i></a>=1.
</td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="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_query_lb.html#ZOLTAN_HG_EDGE_WTS_FN">ZOLTAN_HG_EDGE_WTS_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_FIXED_OBJ_FN">ZOLTAN_NUM_FIXED_OBJ_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="ug_query_lb.html#ZOLTAN_FIXED_OBJ_LIST_FN">ZOLTAN_FIXED_OBJ_LIST_FN</a></b></td>
</tr>
<tr>
<td valign=top><b>Note for<br><i>LB_METHOD = HYPERGRAPH:</i></b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td>
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 this is not equivalent to graph partitioning.
In particular, the edge weights will not be accurate.
</td>
</tr>
<tr>
<td valign="top"><b>Required Query Functions for <i>LB_METHOD = GRAPH</i>:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="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_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr nosave="" valign="top">
<td><br>
</td>
<td nosave="">
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_FN</a></b>
or
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_FN</a></b>
or
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a></b>
</td>
</tr>
<tr>
<td valign="top"><b>Optional Query Functions for <i>LB_METHOD = GRAPH</i>:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td>
<b><a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_MULTI_FN">ZOLTAN_OBJ_SIZE_MULTI_FN</a></b>
or
<b><a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN</a></b> for <i>LB_APPROACH</i>=<i>Repartition</i>.
</td>
</tr>
<tr>
<td><br>
</td>
<td>
<b><a href="ug_query_lb.html#ZOLTAN_PART_MULTI_FN">ZOLTAN_PART_MULTI_FN</a></b>
or
<b><a href="ug_query_lb.html#ZOLTAN_PART_FN">ZOLTAN_PART_FN</a></b> for <i>LB_APPROACH</i>=<i>Repartition</i> and for <a href="ug_alg.html#REMAP"><i>REMAP</i></a>=1.
</td>
</tr>
</tbody>
</table>
<p>
</p>
<hr width="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a
href="ug_alg_patoh.html">Next:&nbsp;
PaToH</a>&nbsp; |&nbsp; <a href="ug_alg_hypergraph.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>

258
thirdParty/Zoltan/docs/ug_html/ug_alg_ptscotch.html vendored Normal file
View File

@ -0,0 +1,258 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Scotch Interface</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_hier.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_parmetis.html">Previous</a></i></b></div>
<h2>
<a NAME="PT-Scotch"></a>Graph partitioning: Scotch/PT-Scotch</h2>
<p>
For more information about graph partitioning, see <a href="ug_alg_parmetis.html">ParMetis</a>.
</p>
<p>
Scotch is a library for ordering and partitioning, developed at LaBRI in Bordeaux, France. PT-Scotch is the parallel module in Scotch. (We use the name PT-Scotch when it applies only to parallel version, Scotch when it concerns at least the serial version.) Scotch is a third-party library in Zoltan and should be obtained separately from the <a href="https://www.labri.fr/perso/pelegrin/scotch/">Scotch web site</a>. Currently, Zoltan supports version 5.1 of Scotch, compiled with the support of PT-Scotch and <i>int</i> coding for vertices, not <i>long</i> (on architectures where <i>sizeof(int) != sizeof(long)</i>).
<p>
If the parameter <a href="#SCOTCH_TYPE">SCOTCH_TYPE</a> is set to LOCAL and the number of processors
is 1 (e.g., mpirun -np 1), the sequential version of Scotch is called.
</p>
<p>
Both the serial (Scotch) and the parallel (PT-Scotch) compute k-way partitioning by doing recursive bisection.
</p>
<p>
Scotch must be used in the context LB_APPROACH=partition, to balance poorly distributed data. Unlike ParMetis, Scotch doesn't support the multiconstraint partitioning feature. However, for single constraint partitioning it seems to produce better results than ParMetis although it requires less memory.
</p>
<table WIDTH="100%" NOSAVE >
<tr>
<td valign="top"><b>Value of LB_METHOD:</b></td>
<td><b>GRAPH</b></td>
</tr>
<tr>
<td valign="top"><b>Value of GRAPH_PACKAGE:</b></td>
<td><b>Scotch</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp; LB_APPROACH<br>
</i></td>
<td>The load balancing approach:. <br>
<i>PARTITION</i>&nbsp; - partition from scratch, not taking
the current data distribution into account<br>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>SCOTCH_METHOD</i></td>
<td>For now, always set to RBISECT</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>SCOTCH_STRAT</i></td>
<td>The Scotch strategy string; see the Scotch documentation.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>SCOTCH_STRAT_FILE</i></td>
<td>A file that contains an arbitrary long Scotch strategy string; see the Scotch documentation.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <a NAME="SCOTCH_TYPE"></a><i>SCOTCH_TYPE</i></td>
<td>Whether or not the parallel library is used. The default value is
<i>GLOBAL</i> and if not set to <i>LOCAL</i>, the parallel graph
partitioning is used.</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp; <i>CHECK_GRAPH</i></td>
<td nosave="">Level of error checking for graph input: 0 = no
checking, 1
= on-processor checking, 2 = full checking. (CHECK_GRAPH==2 is very
slow
and should be used only during debugging).</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp; <i>SCATTER_GRAPH</i></td>
<td nosave="">Scatter graph data by distributing contiguous
chunks of objects
(vertices) of roughly equal size to each processor before calling the
partitioner.
0 = don't scatter;
1 = scatter only if all objects are on a single processor;
2 = scatter if at least one processor owns no objects;
3 = always scatter.&nbsp;</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>GRAPH_SYMMETRIZE</i></td>
<td nosave="">How to symmetrize the graph:
NONE = graph is symmetric and no symmetrization is needed <br/>
TRANSPOSE = if M is adjacency matrix of the input graph, output will be the graph representation of M+M<sup>T</sup> <br/>
BIPARTITE = graph is symmetrized in a bipartite way : [[ 0 M ][M<sup>t</sup> 0]]
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>GRAPH_SYM_WEIGHT</i></td>
<td nosave="">How edge weights are handled during symmetrization:
ADD = weights of each arc are added <br/>
MAX = only the heaviest arc weight is kept <br/>
<!-- ERROR = fail if complementary arcs don't have the same weight. -->
<p>See more informations about graph build options on this <a href="ug_graph_build.html">page</a></p>
</td>
</tr>
<tr>
<td valign="top"><b>Default values:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><i>LB_APPROACH</i> = Partition</td>
</tr>
<tr>
<td><br>
</td>
<td><i>SCOTCH_METHOD</i> = RBISECT</td>
</tr>
<tr>
<td><br>
</td>
<td><i>SCOTCH_STRAT</i> = "" (default Scotch strategy)</td>
</tr>
<tr>
<td><br>
</td>
<td><i>SCOTCH_STRAT_FILE</i> = "" (default Scotch strategy)</td>
</tr>
<tr>
<td><br>
</td>
<td><i>CHECK_GRAPH</i> = 1</td>
</tr>
<tr>
<td><br>
</td>
<td><i>SCATTER_GRAPH </i>= 1</td>
</tr>
<tr>
<td><br>
</td>
<td><i>GRAPH_SYMMETRIZE </i>= NONE</td>
</tr>
<tr>
<td><br>
</td>
<td><i>GRAPH_SYM_WEIGHT </i>= ADD</td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td NOSAVE>
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_F
N</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_F
N</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a></b>
</td>
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_alg_hier.html">Next:&nbsp;
Hybrid Hierarchical Partitioning</a>&nbsp; |&nbsp; <a href="ug_alg_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>

127
thirdParty/Zoltan/docs/ug_html/ug_alg_random.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.7 sun4u) [Netscape]">
<meta name="sandia.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: RANDOM</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_geom.html">Next</a>&nbsp; |&nbsp; <a
href="ug_alg_cyclic.html">Previous</a></i></b></div>
<h2>
<a name="RANDOM"></a>Random</h2>
Random is not really a load-balancing algorithm,
and should be used only for testing!
It takes each object and randomly assigns it to a new part.
Via a parameter, one can alternatively choose to randomly perturb
only a fraction of the objects. The random method does not use weights
and does not attempt to achieve load balance.
<br>
&nbsp;
<table width="100%" nosave="">
<tbody>
<tr>
<td valign="top"><b>Method String:</b></td>
<td><b>Random</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td><br>
</td>
</tr>
<tr>
<td valign="top">&nbsp;&nbsp;&nbsp; <i>RANDOM_MOVE_FRACTION</i></td>
<td>The fraction of objects to randomly move.<br>
1.0 = move all; 0.0 = move nothing</td>
</tr>
<tr>
<td VALIGN=TOP><b>Default:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><i>RANDOM_MOVE_FRACTION</i> = 1.0</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_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
</tbody>
</table>
<p>
<HR WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; |
<a href="ug_alg_geom.html">Next:&nbsp; Geometric (Coordinate-Based) Partitioners</a>
|&nbsp; <a href="ug_alg_cyclic.html">Previous:&nbsp; Cyclic</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

489
thirdParty/Zoltan/docs/ug_html/ug_alg_rcb.html vendored Normal file
View File

@ -0,0 +1,489 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: RCB</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_rib.html">Next</a>&nbsp; |&nbsp; <a
href="ug_alg_geom.html">Previous</a></i></b></div>
<h2>
<a name="RCB"></a>Recursive Coordinate Bisection (RCB)</h2>
An implementation of Recursive Coordinate Bisection (RCB) due to Steve
Plimpton of Sandia National Laboratories is included in Zoltan.
RCB was first proposed as a static load-balancing algorithm by
<a href="ug_refs.html#berger">Berger
and Bokhari</a>, but is attractive as a dynamic load-balancing
algorithm
because it implicitly produces incremental partitions. In RCB, the
computational
domain is first divided into two regions by a cutting plane orthogonal
to one of the coordinate axes so that half the work load is in each of
the sub-regions. The splitting direction is determined by computing in
which coordinate direction the set of objects is most elongated, based
upon the geometric locations of the objects. The sub-regions are then
further
divided by recursive application of the same splitting algorithm until
the number of sub-regions equals the number of processors. Although this
algorithm was first devised to cut into a number of sets which is a power
of two, the set sizes in a particular cut needn't be equal. By adjusting
the part sizes appropriately, any number of equally-sized sets can
be created. If the parallel machine has processors with different
speeds,
sets with nonuniform sizes can also be easily generated. The Zoltan
implementation
of RCB has several parameters which can be modified by the <b><a
href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
function. A recent feature is that RCB allows multiple weights; that
is, one can balance with respect to several load criteria
simultaneously.
Note that there is no guarantee that a desired load balance tolerance
can be achieved using RCB, especially in the multiconstraint case.<br>
<p>
Information about the sub-regions generated by RCB can be obtained by an
application through calls to
<a href="#Zoltan_RCB_Box"><b>Zoltan_RCB_Box</b></a>. This function is not
required to perform load balancing; it only provides auxiliary information
to an application.
<br>&nbsp;
<br>
&nbsp;
<table width="100%" nosave="">
<tbody>
<tr>
<td valign="top"><b>Method String:</b></td>
<td><b>RCB</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td><br>
</td>
</tr>
<tr>
<td valign="top">&nbsp;&nbsp;&nbsp; <i>RCB_OVERALLOC</i></td>
<td>The amount by which to over-allocate temporary storage arrays
for objects
within the RCB algorithm when additional storage is due to changes in
processor
assignments.&nbsp; <br>
1.0 = no extra storage allocated; 1.5 = 50% extra storage; etc.</td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp;&nbsp; RCB_REUSE</i></td>
<td>Flag to indicate whether to use previous cuts as initial
guesses for
the current RCB invocation.&nbsp; <br>
0 = don't use previous cuts; 1 = use previous cuts.</td>
</tr>
<tr>
<td valign="top" nosave="">&nbsp;&nbsp;<i> RCB_OUTPUT_LEVEL</i></td>
<td>Flag controlling the amount of timing and diagnostic output
the routine
produces.&nbsp; <br>
0 = no output; 1 = print summary; 2 = print data for each processor.</td>
</tr>
<tr>
<td valign="top" nosave="">&nbsp;&nbsp;<i> CHECK_GEOM</i></td>
<td>Flag controlling the invocation of input and output error
checking.&nbsp; <br>
0 = don't do checking; 1 = do checking.</td>
</tr>
<tr>
<td valign="top" nosave="">&nbsp;&nbsp;<i> KEEP_CUTS</i></td>
<td>Should information about the cuts determining the RCB
decomposition
be retained? It costs a bit of time to do so, but this information is
necessary
if application wants to add more objects to the decomposition via calls
to <b><a href="ug_interface_augment.html#Zoltan_LB_Point_PP_Assign">Zoltan_LB_Point_PP_Assign</a></b>
or to <b><a href="ug_interface_augment.html#Zoltan_LB_Box_PP_Assign">Zoltan_LB_Box_PP_Assign</a></b>.&nbsp;
<br>
0 = don't keep cuts; 1 = keep cuts.</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<a name="AVERAGE_CUTS"></a><i> AVERAGE_CUTS</i></td>
<td>When set to one, coordinates of RCB cutting planes are computed to be the
average of the coordinates of the closest object on each side of the cut.
Otherwise, coordinates of cutting planes may equal those of one of the
closest objects.
<br>0 = don't average cuts; 1 = average cuts.</td>
</tr>
<tr>
<td valign="top" nosave="">&nbsp;&nbsp;<i> RCB_LOCK_DIRECTIONS</i></td>
<td>Flag that determines whether the order of the directions of
the cuts is kept
constant after they are determined the first time RCB is called.&nbsp; <br>
0 = don't lock directions; 1 = lock directions.</td>
</tr>
<tr>
<td valign="top" nosave="">&nbsp;&nbsp;<i> RCB_SET_DIRECTIONS</i></td>
<td>If this flag is set, the order of cuts is changed so that all
of the cuts
in any direction are done as a group. The number of cuts in each
direction is
determined and then the value of the parameter is used to determine the
order
that those cuts are made in. When 1D and 2D problems are partitioned,
the
directions corresponding to unused dimensions are ignored.&nbsp; <br>
0 = don't order cuts; 1 = xyz; 2 = xzy; 3 = yzx; 4 = yxz; 5 = zxy; 6 =
zyx;</td>
</tr>
<tr>
<td valign="top" nosave="">&nbsp;&nbsp;<i> RCB_RECTILINEAR_BLOCKS</i></td>
<td>Flag controlling the shape of the resulting regions. If this
option is
specified, then when a cut is made, all of the dots located on the cut
are
moved to the same side of the cut. The resulting regions are then
rectilinear. When these dots are treated as a group, then the resulting
load balance may not be as good as when the group of dots is split by
the
cut.&nbsp; <br>
0 = move dots individually; 1 = move dots in groups.<br>
</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> REDUCE_DIMENSIONS</i></td>
<td>
When a 3 dimensional geometry is almost flat, it may make more
sense to treat it as a 2 dimensional geometry when applying the RCB
algorithm. In this case, a 2 dimensional RCB calculation is applied to a plane
that corresponds with the geometry. (This results in cuts that, while
still orthogonal, may no longer be axis aligned.)
If this parameter is set to <B>1</B>, a 3 dimensional
geometry will be treated as 2 dimensional if it is very flat,
or 1 dimensional if it is very thin. A 2 dimensional geometry will
be treated as 1 dimensional if it is very thin.
</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> DEGENERATE_RATIO</i></td>
<td>
If the <B>REDUCE_DIMENSIONS</B> parameter is set, then this parameter
determines when a geometry is considered to be degenerate.
A bounding box which is oriented to the geometry is constructed, and
the lengths of its sides are tested against a ratio of 1 : <B>DEGENERATE_RATIO</B>.
</td>
</tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> RCB_RECOMPUTE_BOX</i></td>
<td>Flag indicating whether the bounding box of set of parts is
recomputed at each level of recursion. By default, the longest direction
of the bounding box is cut during bisection. Recomputing the bounding
box at each level of recursion can produce more effective cut directions
for unusually shaped geometries; the computation does, however, take
additional time and communication, and may cause cut directions to
vary from one invocation of RCB to the next.
<br>0 = don't recompute the bounding box; 1 = recompute the box.</td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp; OBJ_WEIGHTS_COMPARABLE</i><br>
</td>
<td valign="top">In the multiconstraint case, are
the object weights comparable? Do they have the same units and is the
scaling meaningful? For example, if the jth weight corresponds to the
expected time in phase j (measured in seconds), set this parameter to
1. (0 = incomparable, 1 =&nbsp; comparable)<br>
</td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp; RCB_MULTICRITERIA_NORM<br>
</td>
<td valign="top">Norm used in multicriteria
algorithm; this determines how to balance the different weight
constraints. Valid values are 1,2, and 3. Roughly, if the weights
correspond to different phases, then the value 1 (1-norm) tries to
minimize the&nbsp; total time (sum over all phases) while the value 3
(max-norm) attempts to minimize the worst imbalance in any phase. The
2-norm does something in between. Try a different value if you're
not happy with the balance. <br>
</td>
</tr>
<tr>
<td valign="top"><i>&nbsp;&nbsp; RCB_MAX_ASPECT_RATIO</i><br>
</td>
<td valign="top">Maximum allowed ratio between
the largest and smallest side of a subdomain. Must be &gt; 1. <br>
</td>
</tr>
<tr>
<td valign="top"><b>Default:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><i>RCB_OVERALLOC</i> = 1.2</td>
</tr>
<tr>
<td><br>
</td>
<td><i>RCB_REUSE</i> = 0</td>
</tr>
<tr>
<td><br>
</td>
<td><i>RCB_OUTPUT_LEVEL</i> = 0</td>
</tr>
<tr>
<td><br>
</td>
<td><i>CHECK_GEOM</i> = 1</td>
</tr>
<tr>
<td><br>
</td>
<td><i>KEEP_CUTS</i> = 0</td>
</tr>
<tr>
<td></td>
<td><i>AVERAGE_CUTS</i> = 0</td>
</tr>
<tr>
<td><br>
</td>
<td><i>RCB_LOCK_DIRECTIONS</i> = 0</td>
</tr>
<tr>
<td><br>
</td>
<td><i>REDUCE_DIMENSIONS</i> = 0</td>
</tr>
<tr>
<td><br>
</td>
<td><i>DEGENERATE_RATIO</i> = 10</td>
</tr>
<tr>
<td><br>
</td>
<td><i>RCB_SET_DIRECTIONS</i> = 0</td>
</tr>
<tr>
<td><br>
</td>
<td><i>RCB_RECTILINEAR_BLOCKS</i> = 0</td>
</tr>
<tr>
<td></td>
<td><i>RCB_RECOMPUTE_BOX</i> = 0</td>
</tr>
<tr>
<td valign="top"><br>
</td>
<td valign="top"><i>OBJ_WEIGHTS_COMPARABLE</i> = 0<br>
</td>
</tr>
<tr>
<td valign="top"><br>
</td>
<td valign="top"><i>RCB_MULTICRITERIA_NORM</i> = 1<br>
</td>
</tr>
<tr>
<td valign="top"><br>
</td>
<td valign="top"><i>RCB_MAX_ASPECT_RATIO</i> = 10<br>
</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_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr>
<td><br>
</td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a></b></td>
</tr>
<tr>
<td><br>
</td>
<td> <b><a href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b>
or <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
</td>
</tr>
</tbody>
</table>
<p>
<HR WIDTH="100%">
<A NAME="Zoltan_RCB_Box"></A>
<HR WIDTH="100%">
<TABLE WIDTH="100%" NOSAVE >
<TR NOSAVE>
<TD VALIGN=TOP NOSAVE>C:</TD>
<TD WIDTH="85%">
int <B>Zoltan_RCB_Box</B> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <B>Zoltan_Struct</B> *<I> zz</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <I>part</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <I>*ndim</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>*xmin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>*ymin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>*zmin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>*xmax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>*ymax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>*zmax</I>);
</TD>
</TR>
<TR NOSAVE>
<TD VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</TD>
<TD> FUNCTION <B>Zoltan_RCB_Box</B>(<I>zz, part,ndim, xmin, ymin, zmin,
xmax, ymax, zmax</I>)&nbsp;
<BR> INTEGER(Zoltan_INT) :: Zoltan_RCB_Box
<BR> TYPE(Zoltan_Struct), INTENT(IN) :: zz
<BR> INTEGER(Zoltan_INT), INTENT(IN) :: part
<BR> INTEGER(Zoltan_INT), INTENT(OUT) :: ndim
<BR> REAL(Zoltan_DOUBLE), INTENT(OUT) :: xmin, ymin, zmin, xmax, ymax, zmax
</TD>
</TR>
</TABLE>
<HR WIDTH="100%">
In many settings, it is useful to know a part's bounding box
generated by RCB. This bounding box describes the region of space
assigned to a given part.
Given an RCB decomposition of space and a part number,
<B>Zoltan_RCB_Box</b> returns the lower
and upper corners of the region of space assigned to the part.
To use this routine, the parameter <B>KEEP_CUTS</B>
must be set to TRUE when the decomposition is generated. This parameter
will cause the sequence of geometric cuts to be saved, which
is necessary for <B>Zoltan_RCB_Box</B> to do its job.
<BR>&nbsp;
<TABLE WIDTH="100%" >
<TR>
<TD VALIGN=TOP WIDTH="20%"><B>Arguments:</B></TD>
<td WIDTH="80%"></td>
</TR>
<TR>
<TD><I>&nbsp;&nbsp;&nbsp; zz</I></TD>
<TD>Pointer to the Zoltan structure created by <B><A HREF="ug_interface_init.htm
l#Zoltan_Create">Zoltan_Create</A></B>.</TD>
</TR>
<TR>
<TD><I>&nbsp;&nbsp;&nbsp; part</I></TD>
<TD>Part number of part for which the bounding box should be returned.
</td>
</TR>
<TR>
<TD><I>&nbsp;&nbsp;&nbsp; ndim</I></TD>
<TD>Upon return, the number of dimensions in the partitioned geometry.
</td>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp; xmin, ymin, zmin</I></TD>
<TD>Upon return, the coordinates of the lower extent of bounding box
for the part.
If the geometry is two-dimensional, <i>zmin</i> is -DBL_MAX.
If the geometry is one-dimensional, <i>ymin</i> is -DBL_MAX.
</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp; xmax, ymax, zmax</I></TD>
<TD>Upon return, the coordinates of the upper extent of bounding box
for the part.
If the geometry is two-dimensional, <i>zmax</i> is DBL_MAX.
If the geometry is one-dimensional, <i>ymax</i> is DBL_MAX.
</TD>
</TR>
<TR>
<TD><B>Returned Value:</B></TD>
<TD></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</TD>
<TD><A HREF="ug_interface.html#Error Codes">Error code</A>.</TD>
</TR>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; |
<a href="ug_alg_rib.html">Next:&nbsp; Recursive Inertial Bisection (RIB)</a>
|&nbsp; <a href="ug_alg_geom.html">Previous:&nbsp; Geometric (Coordinate-based) Partitioners</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

272
thirdParty/Zoltan/docs/ug_html/ug_alg_reftree.html vendored Normal file
View File

@ -0,0 +1,272 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<TITLE>Zoltan User's Guide: Refinement Tree Based Partition</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_alg_hypergraph.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_hsfc.html">Previous</a></i></b></div>
<H2>
<A NAME="REFTREE"></A>Refinement Tree Partitioning (REFTREE)</H2>
The refinement tree based partitioning method is due to William Mitchell
of the National Institute of Standards and Technology
[<A HREF="ug_refs.html#reftree">Mitchell</A>].
It is closely related to the Octree and Space-Filling Curve methods,
except it uses the tree that represents the adaptive refinement process
that created the grid. This tree is constructed through the tree-based
query functions.
<P>Each node of the refinement tree corresponds to an element that
occurred during the grid refinement process. The first level of the tree
(the children of the root of the tree) corresponds to the initial coarse
grid, one tree node per initial element. It is assumed that the initial
coarse grid does not change through the execution of the program, except
that the local IDs, assignment of elements to processors, and weights
can change. If any other aspect of the coarse grid changes, then the
Zoltan structure should be destroyed and recreated.
The children of a node in the
tree correspond to the elements that were created when the corresponding
element was refined. The children are ordered such that a traversal of
the tree creates a space-filling curve within each initial element.
If the initial elements can be ordered with a contiguous path through them,
then the traversal creates a space-filling curve through all the elements.
Each element has a designated "in" vertex and "out" vertex, with the out
vertex of one element being the same as the in vertex of the next element
in the path, in other words the path goes through a vertex to move from
one element to the next (and does not go out the same vertex it came in).
<P>The user may allow Zoltan to determine the order of the coarse grid
elements, or may specify the order, which might be faster or produce a
better path. If Zoltan determines the order, the user can select between
an order that will produce connected parts, an order based on a Hilbert
Space Filling Curve, or an order based on a Sierpinski Space Filling Curve.
See the parameter REFTREE_INITPATH below. If the user provides the order, then
the in/out vertices must also be supplied. Similarly, the
user may specify the order and in/out vertices of the child elements, or
allow Zoltan to determine them. If the user knows how to provide a good
ordering for the children, this may be significantly faster than the default
general algorithm. However, accelerated forms of the ordering algorithm
are provided for certain types of refinement schemes and should be used in
those cases.
See <B><A HREF="ug_query_lb.html#ZOLTAN_CHILD_LIST_FN">ZOLTAN_CHILD_LIST_FN</A></B>.
If the user always specifies the order, then the vertices and in/out vertices
are not used and do not have to be provided.
<P>Weights are assigned to the nodes of the tree. These weights need not be
only on the leaves (the elements of the final grid), but can also be on
interior nodes (for example, to represent work on coarse grids of a multigrid
algorithm). The default weights are 1.0 at the leaves and 0.0 at the
interior nodes, which produces a partition based on the number of elements
in each part.
An initial tree traversal is used to sum the weights, and a second traversal
to cut the space-filling curve into appropriately-sized pieces and assign
elements to parts. The number of parts is not necessarily equal
to the number of processors.
<P> The following limitations should be removed in the future.
<LI>For multicomponent weights, only the first component is used.
<LI>Heterogeneous architectures are not supported, in the sense that the
computational load is equally divided over the processors. A vector of
relative part sizes is used to determine the weight assigned to each
part, but they are currently all equal. In the future they should
be input to reflect heterogeneity.
<p>
Another limitation is that refinement tree partitioning has not been modified to work with
64-bit global IDs. If 64-bit IDs are selected at configure time with either the
<A HREF="ug_usage.html#Autotools">autotools</A> build or the
<A HREF="ug_usage.html#CMake">CMake</A> build, the method will fail.
<BR>&nbsp;
<BR>&nbsp;
<TABLE WIDTH="100%" NOSAVE >
<TR>
<TD VALIGN=TOP><B>Method String:</B></TD>
<TD><B>REFTREE</B></TD>
</TR>
<TR>
<TD><B>Parameters:</B></TD>
<TD></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>REFTREE_HASH_SIZE</I></TD>
<TD> The size of the hash table to map from global IDs to refinement tree
nodes. Larger values require more memory but may reduce search time.</TD>
</TR>
<TR>
<TD VALIGN=TOP><B>Default:</B></TD>
<TD></TD>
</TR>
<TR>
<TD></TD>
<TD><I>REFTREE_HASH_SIZE</I> = 16384</TD>
</TR>
<TD></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; <I>REFTREE_INITPATH</I></TD>
<TD>
Determines the method for finding an order of the elements in the initial
grid. </BR>
"SIERPINSKI" uses a Sierpinski Space Filling Curve and is most appropriate
for grids consisting of triangles. It is currently limited to 2D. </BR>
"HILBERT" uses a Hilbert Space Filling Curve and is most appropriate for grids
consisting of quadralaterals or hexahedra. </BR>
"CONNECTED" attempts to produce connected parts (guaranteed for triangles
and tetrahedra), however they tend to be stringy, i.e., less compact than the
SFC methods. It is most appropriate when connected parts are required. </BR>
An invalid character string will invoke the default method.
</TD>
</TR>
<TR>
<TD VALIGN=TOP><B>Default:</B></TD>
<TD></TD>
</TR>
<TR>
<TD></TD>
<TD><I>REFTREE_INITPATH</I> = "SIERPINSKI" if the grid contains only triangles</BR>
<I>REFTREE_INITPATH</I> = "HILBERT" otherwise
</BR></BR>
<I>NOTE:</I> In Zoltan versions 1.53 and earlier the default was "CONNECTED".
To reproduce old results, use <I>REFTREE_INITPATH</I> = "CONNECTED".
</TD>
</TR>
<TR>
<TD VALIGN=TOP><B>Required Query Functions:</B></TD>
<TD></TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_NUM_COARSE_OBJ_FN">ZOLTAN_NUM_COARSE_OBJ_FN</A></B></TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_COARSE_OBJ_LIST_FN">ZOLTAN_COARSE_OBJ_LIST_FN</A></B>
or <B><A HREF="ug_query_lb.html#ZOLTAN_FIRST_COARSE_OBJ_FN">ZOLTAN_FIRST_COARSE_OBJ_FN</A></B>/<B><A HREF="ug_query_lb.html#ZOLTAN_NEXT_COARSE_OBJ_FN">ZOLTAN_NEXT_COARSE_OBJ_FN</A></B>
pair
</TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_NUM_CHILD_FN">ZOLTAN_NUM_CHILD_FN</A></B></TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_CHILD_LIST_FN">ZOLTAN_CHILD_LIST_FN</A></B></TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_CHILD_WEIGHT_FN">ZOLTAN_CHILD_WEIGHT_FN</A></B></TD>
</TR>
<TR>
<TD></TD>
<TD>The following functions are needed only if the order of the initial
elements will be determined by a space filling curve method:</TD>
</TR>
<TR>
<TD></TD>
<TD><B><A HREF="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</A></B></TD>
</TR>
<TR>
<TD></TD>
<TD>
<B><A HREF="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</A></B><B>
or
<B><A HREF="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</A></B>
</TD>
</TR>
<TR>
</TABLE>
&nbsp;
<P>
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_alg_hypergraph.html">Next:&nbsp; Hypergraph Partitioning</A>&nbsp;
|&nbsp; <A HREF="ug_alg_hsfc.html">Previous:&nbsp;&nbsp; Hilbert Space-Filling
Curve Partitioning</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

258
thirdParty/Zoltan/docs/ug_html/ug_alg_rib.html vendored Normal file
View File

@ -0,0 +1,258 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: RIB</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_alg_hsfc.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_rcb.html">Previous</a></i></b></div>
<h2>
<a NAME="RIB"></a>Recursive Inertial Bisection (RIB)</h2>
An implementation of Recursive Inertial Bisection (RIB) is included in
Zoltan. RIB was proposed as a load-balancing algorithm by
<a href="ug_refs.html#williams">Williams</a> and later studied
by <a href="ug_refs.html#taylor">Taylor and Nour-Omid</a>, but its
origin is unclear. RIB is similar to RCB in that it divides the domain based on
the location of the objects being partitioned by use of cutting planes.
In RIB, the computational domain is first divided into two regions by a
cutting plane orthogonal to the longest direction of the domain so that half
the work load is in each of the sub-regions. The sub-regions are then further
divided by recursive application of the same splitting algorithm until
the number of sub-regions equals the number of processors. Although this
algorithm was first devised to cut into a number of sets which is a power
of two, the set sizes in a particular cut needn't be equal. By adjusting
the part sizes appropriately, any number of equally-sized sets can
be created. If the parallel machine has processors with different speeds,
sets with nonuniform sizes can also be easily generated. The Zoltan implementation
of RIB has several parameters which can be modified by the <b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
function.
<p>
RIB currently does not support multiple vertex weights. For such cases, use RCB instead.
</p>
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Method String:</b></td>
<td><b>RIB</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>RIB_OVERALLOC</i></td>
<td>The amount by which to over-allocate temporary storage arrays for objects
within the RIB algorithm when additional storage is due to changes in processor
assignments.&nbsp;
<br>1.0 = no extra storage allocated; 1.5 = 50% extra storage; etc.</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> RIB_OUTPUT_LEVEL</i></td>
<td>Flag controlling the amount of timing and diagnostic output the routine
produces.&nbsp;
<br>0 = no output; 1 = print summary; 2 = print data for each processor.</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> CHECK_GEOM</i></td>
<td>Flag controlling the invocation of input and output error checking.&nbsp;
<br>0 = don't do checking; 1 = do checking.</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> KEEP_CUTS</i></td>
<td>Should information about the cuts determining the RIB decomposition
be retained? It costs a bit of time to do so, but this information is necessary
if application wants to add more objects to the decomposition via calls
to <b><a href="ug_interface_augment.html#Zoltan_LB_Point_PP_Assign">Zoltan_LB_Point_PP_Assign</a></b>
or to <b><a href="ug_interface_augment.html#Zoltan_LB_Box_PP_Assign">Zoltan_LB_Box_PP_Assign</a></b>.&nbsp;
<br>0 = don't keep cuts; 1 = keep cuts.</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> AVERAGE_CUTS</i></td>
<td>When set to one, coordinates of RIB cutting planes are computed to be the
average of the coordinates of the closest object on each side of the cut.
Otherwise, coordinates of cutting planes may equal those of one of the
closest objects.
<br>0 = don't average cuts; 1 = average cuts.</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> REDUCE_DIMENSIONS</i></td>
<td>
When a 3 dimensional geometry is almost flat, it may make more
sense to treat it as a 2 dimensional geometry when applying the RIB
algorithm. (Coordinate values in the omitted direction are ignored
for the purposes of partitioning.)
If this parameter is set to <B>1</B>, a 3 dimensional
geometry will be treated as 2 dimensional if it is very flat,
or 1 dimensional if it is very thin. A 2 dimensional geometry will
be treated as 1 dimensional if it is very thin.
</td>
</tr>
<tr>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;<i> DEGENERATE_RATIO</i></td>
<td>
If the <B>REDUCE_DIMENSIONS</B> parameter is set, then this parameter
determines when a geometry is considered to be degenerate.
A bounding box which is oriented to the geometry is constructed, and
the lengths of its sides are tested against a ratio of 1 : <B>DEGENERATE_RATIO</B>.
</td>
</tr>
<tr>
<td VALIGN=TOP><b>Default:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><i>RIB_OVERALLOC</i> = 1.2</td>
</tr>
<tr>
<td></td>
<td><i>RIB_OUTPUT_LEVEL</i> = 0</td>
</tr>
<tr>
<td></td>
<td><i>CHECK_GEOM</i> = 1</td>
</tr>
<tr>
<td></td>
<td><i>KEEP_CUTS</i> = 0</td>
</tr>
<tr>
<td></td>
<td><i>AVERAGE_CUTS</i> = 0</td>
</tr>
<tr>
<td></td>
<td><i>REDUCE_DIMENSIONS</i> = 0</td>
</tr>
<tr>
<td></td>
<td><i>DEGENERATE_RATIO</i> = 10</td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a></b></td>
</tr>
<tr>
<td></td>
<td>
<b><a href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b>
or <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
</td>
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; |
<a href="ug_alg_hsfc.html">Next:&nbsp;
Hilbert Space-Filling Curve Partitioning</a> |&nbsp; <a href="ug_alg_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>

81
thirdParty/Zoltan/docs/ug_html/ug_alg_simple.html vendored Normal file
View File

@ -0,0 +1,81 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Simple Partitioners for Testing</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_block.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg.html">Previous</a></i></b></div>
<h2>
<a name="SIMPLE"></a>Simple Partitioners for Testing</h2>
Zoltan includes two very simple partitioners for testing initial
implementations of Zoltan in applications. These partitioners are
intended only for testing and to serve as examples.
They use neither geometry nor connectivity (graph/hypergraph), so they
require very few query functions (only two!).
<blockquote>
<a href="ug_alg_block.html">Block partitioning</a> (BLOCK)
<br><a href="ug_alg_random.html">Random partitioning</a> (RANDOM)
</blockquote>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_alg_block.html">Next:&nbsp;
Block Partitioning</a>&nbsp; |&nbsp; <a href="ug_alg.html">Previous:&nbsp;
Load-Balancing Algorithms and Parameters</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

692
thirdParty/Zoltan/docs/ug_html/ug_backward.html vendored Normal file
View File

@ -0,0 +1,692 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Backward Compatilibity</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_refs.html">Next</a>&nbsp; |&nbsp; <a href="ug_release.html">Previous</a></i></b></div>
<!---------------------------------------------------------------------------->
<h2>
Backward Compatibility with Previous Versions of Zoltan
</h2>
As new features have been added to Zoltan, backward compatibility with previous
versions of Zoltan has been maintained. Thus, users of previous versions of
Zoltan can upgrade to a new version <b> without changing their application
source code</b>.
Modifications to application source code are needed <b>only</b> if the
applications use new Zoltan functionality.
<p>
Enhancements to the Zoltan interface are described below.
<blockquote>
<a href="#Backward v3.8">Versions 3.8 and higher</a>
<br><a href="#Backward v3.6">Versions 3.6 and higher</a>
<br><a href="#Backward v3.2">Versions 3.2 and higher</a>
<br><a href="#Backward v3.1">Versions 3.1 and higher</a>
<br><a href="#Backward v3.0">Versions 3.0 and higher</a>
<br><a href="#Backward v1.5">Versions 1.5 and higher</a>
<br><a href="#Backward v1.3">Versions 1.3 and higher</a>
</blockquote>
<!---------------------------------------------------------------------------->
<h2><a name="Backward v3.8"></a>
<hr>Backward Compatibility: Versions 3.8 and higher
</h2>
<ul>
<li>
Zoltan is now released under Trilinos' BSD license.
</li>
<li>
All deprecated features in <a href="#Backward v3.6">version 3.6</a>
are now removed from Zoltan. See notes <a href="#Backward v3.6">below</a>.
</li>
</ul>
<!---------------------------------------------------------------------------->
<h2><a name="Backward v3.6"></a>
<hr>Backward Compatibility: Versions 3.6 and higher
</h2>
<ul>
<li>
Interfaces to Zoltan defined in lbi_const.h are now deprecated. Users should
upgrade to interfaces in zoltan.h. File lbi_const.h should not be included
in user files; rather, file zoltan.h should be included. File lbi_const.h will
not be distributed in future versions of Zoltan.
</li>
<li>
The OCTPART/OCTREE partitioning method is deprecated and will not be supported
in future versions of Zoltan. This method is now disabled by default in the
CMake build system; it can be enabled with CMake configuration flag
-DZoltan_ENABLE_OCT:BOOL=ON. Users should switch to Zoltan method HSFC
(Hilbert Space-Filling Curve partitioning), which should provide very similar
decompositions, or consider RCB partitioning.
</li>
</ul>
<!---------------------------------------------------------------------------->
<h2><a name="Backward v3.2"></a>
<hr>Backward Compatibility: Versions 3.2 and higher
</h2>
Interfaces to
<a href="ug_interface_color.html">Zoltan_Color</a>,
<a href="ug_interface_order.html">Zoltan_Order</a> and
<a href="ug_interface_lb.html#Zoltan_LB_Eval">Zoltan_LB_Eval</a> have changed.
<p>
The Zoltan native build environment, while still distributed, will no
longer be supported. Users should use the
<a href="ug_usage.html#Building the Library">autotools or CMake</a> systems.
Builds of the Zoltan F90 interface are supported in both autotools and
CMake.
<!---------------------------------------------------------------------------->
<h2><a name="Backward v3.1"></a>
<hr>Backward Compatibility: Versions 3.1 and higher
</h2>
Terminology referring to partitions and parts was clarified.
A "partition" describes the entire layout of the data across
processes. A "part" is a subset of the data assigned to a
single process. A partition is made up of many parts; the set
of all the parts is a partition.
<p>
We applied this naming convention more consistently throughout Zoltan.
Old parameters NUM_GLOBAL_PARTITIONS and NUM_LOCAL_PARTITIONS have been
more accurately renamed <a href="ug_alg.html#NUM_GLOBAL_PARTS">NUM_GLOBAL_PARTS</a> and
<a href="ug_alg.html#NUM_LOCAL_PARTS">NUM_LOCAL_PARTS</a>. Old query functions
ZOLTAN_PARTITIONS_MULTI_FN and ZOLTAN_PARTITION_FN have been more
accurately renamed
<a href="ug_query_lb.html#ZOLTAN_PART_MULTI_FN">ZOLTAN_PART_MULTI_FN</a>
and
<a href="ug_query_lb.html#ZOLTAN_PART_FN">ZOLTAN_PART_FN</a>.
However, in both cases, the old naming convention still works in the
Zoltan library.
<!---------------------------------------------------------------------------->
<h2><a name="Backward v3.0"></a>
<hr>Backward Compatibility: Versions 3.0 and higher
</h2>
A new naming convention was implemented to better categorize partitioning
methods. For more details, see parameters
<blockquote>
<a href="ug_alg.html#LB_METHOD">LB_METHOD</a>, <br>
<a href="ug_alg.html#LB_APPROACH">LB_APPROACH</a>, <br>
<a href="ug_alg_graph.html">GRAPH_PACKAGE</a>, and <br>
<a href="ug_alg_hypergraph.html">HYPERGRAPH_PACKAGE</a>.
</blockquote>
Former valid values of LB_METHOD should continue to work. In particular,
values of LB_METHOD for geometric partitioners
<a href="ug_alg_rcb.html">RCB</a>,
<a href="ug_alg_rib.html">RIB</a>,
<a href="ug_alg_hsfc.html">HSFC</a>, and
<a href="ug_alg_reftree.html">REFTREE</a> are unchanged.
<p>
The default graph partitioner has been changed from
<a href="ug_alg_parmetis.html">ParMETIS</a> to
<a href="ug_alg_phg.html">Zoltan PHG</a>. This change was made to
provide graph partitioning capability without reliance on the third-party
library ParMETIS.
<p>
Because Zoltan is designed primarily for dynamic load balancing,
The default partitioning approach
<a href="ug_alg.html#LB_APPROACH">LB_APPROACH</a>
is now "repartition." This change affects only Zoltan's hypergraph
partitioner <a href="ug_alg_phg.html">PHG</a>.
<!---------------------------------------------------------------------------->
<h2><a name="Backward v1.5"></a>
<hr>Backward Compatibility: Versions 1.5 and higher
</h2>
The ability to generate more parts than processors was added to Zoltan
in version 1.5. Thus, Zoltan's partitioning and migration routines were
enhanced to return and use both part assignments and processor assignments.
New interface and query functions were added to support this additional
information. All former Zoltan <a href="ug_param.html">parameters</a>
apply to the new functions as they did to the old; new parameters
<a href="ug_alg.html#NUM_GLOBAL_PARTS"><i>NUM_GLOBAL_PARTS</i></a>
and
<a href="ug_alg.html#NUM_LOCAL_PARTS"><i>NUM_LOCAL_PARTS</i></a>
apply only to the new functions.
<p>
The table below lists the Zoltan function that uses both part and
processor information, along with the analogous function that returns only
processor information. Applications requiring only one part per
processor can use either version of the functions.
<p>
<table border="1" cellpadding="5">
<tr>
<td>
<b>Function with Part and Processor info (v1.5 and higher)</b>
</td>
<td>
<b>Function with only Processor info (v1.3 and higher)</b>
</td>
</tr>
<tr>
<td>
<a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a>
</td>
<td>
<a href="ug_interface_lb.html#Zoltan_LB_Balance">Zoltan_LB_Balance</a>
</td>
</tr>
<tr>
<td>
<a href="ug_interface_augment.html#Zoltan_LB_Point_PP_Assign">Zoltan_LB_Point_PP_Assign</a>
</td>
<td>
<a href="ug_interface_augment.html#Zoltan_LB_Point_Assign">Zoltan_LB_Point_Assign</a>
</td>
</tr>
<tr>
<td>
<a href="ug_interface_augment.html#Zoltan_LB_Box_PP_Assign">Zoltan_LB_Box_PP_Assign</a>
</td>
<td>
<a href="ug_interface_augment.html#Zoltan_LB_Box_Assign">Zoltan_LB_Box_Assign</a>
</td>
</tr>
<tr>
<td>
<a href="ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a>
</td>
<td>
<a href="ug_interface_mig.html#Zoltan_Compute_Destinations">Zoltan_Compute_Destinations</a>
</td>
</tr>
<tr>
<td>
<a href="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a>
</td>
<td>
<a href="ug_interface_mig.html#Zoltan_Help_Migrate">Zoltan_Help_Migrate</a>
</td>
</tr>
<tr>
<td>
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN">ZOLTAN_PRE_MIGRATE_PP_FN</a>
</td>
<td>
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_FN">ZOLTAN_PRE_MIGRATE_FN</a>
</td>
</tr>
<tr>
<td>
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN">ZOLTAN_MID_MIGRATE_PP_FN</a>
</td>
<td>
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_FN">ZOLTAN_MID_MIGRATE_FN</a>
</td>
</tr>
<tr>
<td>
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN">ZOLTAN_POST_MIGRATE_PP_FN</a>
</td>
<td>
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_FN">ZOLTAN_POST_MIGRATE_FN</a>
</td>
</tr>
</table>
<p>
To continue using the v1.3 partition functions, no changes to C or Fortran90
applications are needed. Zoltan interfaces from versions earlier than 1.3
are also still supported (see
<a href="#Backward v1.3">below</a>),
requiring no changes to application programs.
<p>
To use the new v1.5 partitioning functions:
<ul>
<li>
C users must include file <i>zoltan.h</i> in their applications and edit
their applications to use the appropriate new functions.
</li>
<li>
Fortran90 users must put
<a href="ug_fortran_api.html#fortran ug api query">user-defined data types</a>
in <i>zoltan_user_data.f90</i> and edit their applications to
use the appropriate new functions. The new partitioning functions do not
work with user-defined data types in <i>lb_user_const.f90</i>.
</li>
</ul>
<!---------------------------------------------------------------------------->
<h2><a name="Backward v1.3"></a>
<hr>Backward Compatibility: Versions 1.3 and higher
</h2>
<p>
Versions of Zoltan before version 1.3 used a different naming convention for
the Zoltan interface and query functions. All functions in Zoltan v.1.3 and
above
are prefixed with <b>Zoltan_</b>; earlier versions were prefixed with
<b>LB_</b>.
<p>
<b>Zoltan versions 1.3 and above maintain backward compatibility with the
earlier
Zoltan interface.</b> Thus, applications that used earlier versions of Zoltan
can continue using Zoltan <b>without changing their source code</b>.
<p>
Only two
changes are needed to build the application with Zoltan v.1.3 and higher:
<ul>
<li>
All Zoltan include files are now in directory <i>Zoltan/include</i>.
Thus, application include paths must point to this directory.
<br>(Previously, include files were in <i>Zoltan/lb</i>.)
<li>
Applications link with Zoltan now by specifying only <i>-lzoltan</i>.
<br>(Previously, applications had to link with <i>-lzoltan -lzoltan_comm
-lzoltan_mem</i>.)
</ul>
<p>
While it is not necessary for application developers to modify their
source code to use Zoltan v.1.3 and above, those who want to update their
source code
should do the following in their application source files:
<ul>
<li>
Replace Zoltan calls and constants (<b>LB_*</b>) with new names. The new
names can be found through the <a href="#Backward Index">index below</a>.
<li>
C programs: Include file <i>zoltan.h</i> instead of <i>lbi_const.h</i>.
<li>
F90 programs: Put <a href="ug_fortran_api.html#fortran ug api query">user-defined data types</a> in file <i>zoltan_user_data.f90</i> instead of <i>lb_user_const.f90</i>.
</ul>
<!---------------------------------------------------------------------------->
<h4>
<a NAME="Backward Index"></a>Backward Compatilibity Index for Interface and Query Functions
</h4>
<table border="1" cellpadding="5">
<tr>
<td>
<b>Name in Earlier Zoltan Versions</b>
</td>
<td>
<b>Name in Zoltan Version 1.3 and higher</b>
</td>
</tr>
<tr>
<td>
LB_BORDER_OBJ_LIST_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_BORDER_OBJ_LIST_FN">ZOLTAN_BORDER_OBJ_LIST_FN</a>
</td>
</tr>
<tr>
<td>
LB_Balance
</td>
<td>
<a href="ug_interface_lb.html#Zoltan_LB_Balance">Zoltan_LB_Balance</a>
</td>
</tr>
<tr>
<td>
LB_Box_Assign
</td>
<td>
<a href="ug_interface_augment.html#Zoltan_LB_Box_Assign">Zoltan_LB_Box_Assign</a>
</td>
</tr>
<tr>
<td>
LB_CHILD_LIST_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_CHILD_LIST_FN">ZOLTAN_CHILD_LIST_FN</a>
</td>
</tr>
<tr>
<td>
LB_CHILD_WEIGHT_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_CHILD_WEIGHT_FN">ZOLTAN_CHILD_WEIGHT_FN</a>
</td>
</tr>
<tr>
<td>
LB_COARSE_OBJ_LIST_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_COARSE_OBJ_LIST_FN">ZOLTAN_COARSE_OBJ_LIST_FN</a>
</td>
</tr>
<tr>
<td>
LB_Compute_Destinations
</td>
<td>
<a href="ug_interface_mig.html#Zoltan_Compute_Destinations">Zoltan_Compute_Destinations</a>
</td>
</tr>
<tr>
<td>
LB_Create
</td>
<td>
<a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a>
</td>
</tr>
<tr>
<td>
LB_Destroy
</td>
<td>
<a href="ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</a>
</td>
</tr>
<tr>
<td>
LB_EDGE_LIST_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a>
</td>
</tr>
<tr>
<td>
LB_Eval
</td>
<td>
<a href="ug_interface_lb.html#Zoltan_LB_Eval">Zoltan_LB_Eval</a>
</td>
</tr>
<tr>
<td>
LB_FIRST_BORDER_OBJ_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_FIRST_BORDER_OBJ_FN">ZOLTAN_FIRST_BORDER_OBJ_FN</a>
</td>
</tr>
<tr>
<td>
LB_FIRST_COARSE_OBJ_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_FIRST_COARSE_OBJ_FN">ZOLTAN_FIRST_COARSE_OBJ_FN</a>
</td>
</tr>
<tr>
<td>
LB_FIRST_OBJ_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_FIRST_OBJ_FN">ZOLTAN_FIRST_OBJ_FN</a>
</td>
</tr>
<tr>
<td>
LB_Free_Data
</td>
<td>
<a href="ug_interface_lb.html#Zoltan_LB_Free_Data">Zoltan_LB_Free_Data</a>
</td>
</tr>
<tr>
<td>
LB_GEOM_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a>
</td>
</tr>
<tr>
<td>
LB_Help_Migrate
</td>
<td>
<a href="ug_interface_mig.html#Zoltan_Help_Migrate">Zoltan_Help_Migrate</a>
</td>
</tr>
<tr>
<td>
LB_Initialize
</td>
<td>
<a href="ug_interface_init.html#Zoltan_Initialize">Zoltan_Initialize</a>
</td>
</tr>
<tr>
<td>
LB_MID_MIGRATE_FN
</td>
<td>
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_FN">ZOLTAN_MID_MIGRATE_FN</a>
</td>
</tr>
<tr>
<td>
LB_NEXT_BORDER_OBJ_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_NEXT_BORDER_OBJ_FN">ZOLTAN_NEXT_BORDER_OBJ_FN</a>
</td>
</tr>
<tr>
<td>
LB_NEXT_COARSE_OBJ_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_NEXT_COARSE_OBJ_FN">ZOLTAN_NEXT_COARSE_OBJ_FN</a>
</td>
</tr>
<tr>
<td>
LB_NEXT_OBJ_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_NEXT_OBJ_FN">ZOLTAN_NEXT_OBJ_FN</a>
</td>
</tr>
<tr>
<td>
LB_NUM_BORDER_OBJ_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_NUM_BORDER_OBJ_FN">ZOLTAN_NUM_BORDER_OBJ_FN</a>
</td>
</tr>
<tr>
<td>
LB_NUM_CHILD_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_NUM_CHILD_FN">ZOLTAN_NUM_CHILD_FN</a>
</td>
</tr>
<tr>
<td>
LB_NUM_COARSE_OBJ_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_NUM_COARSE_OBJ_FN">ZOLTAN_NUM_COARSE_OBJ_FN</a>
</td>
</tr>
<tr>
<td>
LB_NUM_EDGES_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a>
</td>
</tr>
<tr>
<td>
LB_NUM_GEOM_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a>
</td>
</tr>
<tr>
<td>
LB_NUM_OBJ_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a>
</td>
</tr>
<tr>
<td>
LB_OBJ_LIST_FN
</td>
<td>
<a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a>
</td>
</tr>
<tr>
<td>
LB_OBJ_SIZE_FN
</td>
<td>
<a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN</a>
</td>
</tr>
<tr>
<td>
LB_PACK_OBJ_FN
</td>
<td>
<a href="ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN</a>
</td>
</tr>
<tr>
<td>
LB_POST_MIGRATE_FN
</td>
<td>
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_FN">ZOLTAN_POST_MIGRATE_FN</a>
</td>
</tr>
<tr>
<td>
LB_PRE_MIGRATE_FN
</td>
<td>
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_FN">ZOLTAN_PRE_MIGRATE_FN</a>
</td>
</tr>
<tr>
<td>
LB_Point_Assign
</td>
<td>
<a href="ug_interface_augment.html#Zoltan_LB_Point_Assign">Zoltan_LB_Point_Assign</a>
</td>
</tr>
<tr>
<td>
LB_Set_Fn
</td>
<td>
<a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>
</td>
</tr>
<tr>
<td>
LB_Set_&lt;<i>lb_fn_type</i>>_Fn
</td>
<td>
<a href="ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</a>
</td>
</tr>
<tr>
<td>
LB_Set_Method
</td>
<td>
<a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
with parameter <a href="ug_alg.html#LB_METHOD"><i>LB_METHOD</i></a>
</td>
</tr>
<tr>
<td>
LB_Set_Param
</td>
<td>
<a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
</td>
</tr>
<tr>
<td>
LB_UNPACK_OBJ_FN
</td>
<td>
<a href="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN</a>
</td>
</tr>
</table>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_refs.html">Next:&nbsp; References</a>&nbsp; |&nbsp; <a href="ug_release.html">Previous:&nbsp; Release Notes</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

252
thirdParty/Zoltan/docs/ug_html/ug_color.html vendored Normal file
View File

@ -0,0 +1,252 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Coloring Algorithms</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_color_parallel.html">Next</a>&nbsp; |&nbsp; <a href="ug_order_ptscotch.html">Previous</a></i></b></div>
<!---------------------------------------------------------------------------->
<h2>
<a NAME="Coloring Algorithms"></a>Coloring Algorithms</h2>
<p>The following coloring algorithms are currently included in the Zoltan
library:
<blockquote><a href="ug_color_parallel.html">Parallel Coloring
</a></blockquote>
They are accessed through calls to <b><a href="ug_interface_color.html#Zoltan_Color">Zoltan_Color</a></b>.
<p><!---------------------------------------------------------------------------->
<h3>
<a NAME="Color Parameters"></a>
<hr><b>Coloring Parameters</b></h3>
While the overall behavior of Zoltan is controlled by <a href="ug_param.html">general
Zoltan parameters</a>, the behavior of each coloring method is controlled
by parameters specific to coloring which are also set by calls to <b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
These parameters are described below.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td VALIGN=TOP><b>Parameters:</b></td>
<td></td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="COLORING_PROBLEM"></a>&nbsp;&nbsp;<i>COLORING_PROBLEM</i></td>
<td>
The specific coloring problem to be solved. Supported values include
"DISTANCE-1" (the standard vertex coloring problem), "DISTANCE-2"
(useful for Jacobian coloring) and "PARTIAL-DISTANCE-2".
When called with "PARTIAL-DISTANCE-2", only the objects
listed in <i>global_ids</i> (paramter of <b><a
href="ug_interface_color.html#Zoltan_Color">Zoltan_Color</a></b>
function) are colored. "BIPARTITE" is an alternative name for "PARTIAL-DISTANCE-2".
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="SUPERSTEP_SIZE"></a>&nbsp;&nbsp;<i>SUPERSTEP_SIZE</i></td>
<td>Number of local objects to be colored on each processor before
exchanging color information. SUPERSTEP_SIZE should be greater than 0.
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="COMM_PATTERN"></a><i>&nbsp;&nbsp;COMM_PATTERN</i></td>
<td>Valid values are "S" (synchronous) and "A" (asynchronous). If
synchronous communication is selected, processors are forced to wait
for the color information from all other processors to be received
before proceeding with coloring of the next SUPERSTEP_SIZE number of
local objects. If asynchronous communication is selected, there is no
such restriction.
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="VERTEX_VISIT_ORDER"></a><i>&nbsp;&nbsp;VERTEX_VISIT_ORDER</i></td>
<td>Valid values are "I" (internal first), "B" (boundary first) and
"U" (unordered), "N" (natural), "L" (largest degree first), "S"
(smallest degree last). If "I" is selected, each processor colors
its internal objects before boundary objects. If "B" is selected,
each processor colors its boundary objects first. If "U" is
selected, there is no such distinction between internal and boundary
objects. "N" is equivalent to "U". If "L" is selected, the objects
are sorted according to their number of neighbors so that the object
with larger number of neighbors are colored first. If "S" is
selected, the order is dynamically constructed; the object with
smallest number of neighbors will be colored last and is
temporarily removed from the graph. This process repeats itself
until all objects are ordered. </td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="RECOLORING_NUM_OF_ITERATIONS"></a><i>&nbsp;&nbsp;RECOLORING_NUM_OF_ITERATIONS </i></td>
<td>Number of distance-1 recoloring iterations to be performed after first
coloring phase. A value of zero disables recoloring.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="RECOLORING_TYPE"></a><i>&nbsp;&nbsp;RECOLORING_TYPE</i></td>
<td> Valid values are "SYNCHRONOUS" and "ASYNCHRONOUS". If
"SYNCHRONOUS" is selected, each processor waits for its neighboors to
finish processing one color before processing the next one. If
"ASYNCHRONOUS" is selected, each processor itself recolors all of its
vertices in specified order, independent from other processors. It is
then necessary to detect and resolve conflicts. </td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="RECOLORING_PERMUTATION"></a><i>&nbsp;&nbsp;RECOLORING_PERMUTATION</i></td>
<td>Valid values are "FORWARD", "REVERSE", "NONDECREASING" and
"NONINCREASING". The "FORWARD" permutation orders the colors in
increasing order of their color identifiers. The "REVERSE" permutation
is the opposite one. The "NONDECREASING" orders the colors in
non-decreasing order of the number of time the colors are used in the
whole graph. In other words, the less used colors are colored
first. "NONINCREASING" is the opposite of "NONDECREASING".
</td>
</tr>
<!-- commenting this section
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="COLORING_METHOD"></a><i>&nbsp;&nbsp;COLORING_METHOD</i></td>
<td>Currently only "F" (first-fit) is implemented. By using "F", the
smallest available color that will not cause a conflict is assigned to
the object that is being colored. </td>
</tr>
-->
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="GRAPH_METHOD"></a><i>&nbsp;&nbsp;Options for graph build</i></td>
<td>See more informations about graph build options on this <a href="ug_graph_build.html">page</a></td>
</tr>
<tr VALIGN=TOP>
<td VALIGN=TOP><a NAME="Default_Parameter_Values"></a><b>Default Values:</b></td>
<td></td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>COLORING_PROBLEM</i> = DISTANCE-1</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>SUPERSTEP_SIZE </i>= 100</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>COMM_PATTERN </i>= S</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>VERTEX_VISIT_ORDER</i> = I</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<tr VALIGN=TOP>
<td></td>
<td><i>RECOLORING_NUM_OF _ITERATIONS</i> = 0</td>
</tr>
<tr VALIGN=TOP>
<tr VALIGN=TOP>
<td></td>
<td><i>RECOLORING_TYPE</i> = SYNCHRONOUS</td>
</tr>
<tr VALIGN=TOP>
<tr VALIGN=TOP>
<td></td>
<td><i>RECOLORING_PERMUTATION</i> = NONDECREASING</td>
</tr>
<tr VALIGN=TOP>
<!-- commenting
<td><i>COLORING_METHOD</i> = F</td>
-->
</tr>
</table>
<p><!---------------------------------------------------------------------------->
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_color_parallel.html">Next:&nbsp;
Parallel Coloring</a>&nbsp; |&nbsp; <a href="ug_order_parmetis.html">Previous:&nbsp;
Nested Dissection by ParMETIS</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

192
thirdParty/Zoltan/docs/ug_html/ug_color_parallel.html vendored Normal file
View File

@ -0,0 +1,192 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Parallel Coloring</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_util.html">Next</a>&nbsp; |&nbsp; <a href="ug_color.html">Previous</a></i></b></div>
<h2>
<a NAME="Parallel Coloring"></a>Parallel Coloring</h2>
The parallel coloring algorithm in Zoltan is based on the work of
<a href="ug_refs.html#d1color">Boman et al.</a> for distance-1
coloring and <a href="ug_refs.html#d2color">Bozdag et al.</a> for
distance-2 coloring. It was implemented in Zoltan by Doruk Bozdag and
Umit V. Catalyurek, Department of Biomedical Informatics, the Ohio State
University. Distance-1 coloring algorithm is an iterative data
parallel algorithm that proceeds in two-phased rounds. In the first
phase, processors concurrently color the vertices assigned to
them. Adjacent vertices colored in the same parallel step of this
phase may result in inconsistencies. In the second phase, processors
concurrently check the validity of the colors assigned to their
respective vertices and identify a set of vertices that needs to be
re-colored in the next round to resolve the detected
inconsistencies. The algorithm terminates when every vertex has been
colored correctly. To reduce communication frequency, the coloring
phase is further decomposed into computation and communication
sub-phases. In a communication sub-phase processors exchange recent
color information. During a computation sub-phase, a number of
vertices determined by the SUPERSTEP_SIZE parameter, rather than a
single vertex, is colored based on currently available color
information. With an appropriate choice of a value for SUPERSTEP_SIZE,
the number of ensuing conflicts can be kept low while at the same time
preventing the runtime from being dominated by the sending of a large
number of small messages. The distance-2 graph coloring problem aims
at partitioning the vertex set of a graph into the fewest sets
consisting of vertices pairwise at distance greater than two from each
other. The algorithm is an extension of the parallel distance-1
coloring algorithm.
<br/><br/>
In distance-1 coloring, a
post-processing to coloring, named as <em>recoloring</em>, is also implemented
in Zoltan by Ahmet Erdem Sariyuce, Erik Saule and Umit V. Catalyurek,
Department of Biomedical Informatics, the Ohio State University. Its
details are presented in <a href="ug_refs.html#sariyuce">Sariyuce et
al.<a/>. Recoloring is an iterative improvement algorithm first
proposed in <a href="ug_refs.html#culberson">Culberson 92<a/> for
sequential architecture. The algorithm uses an existing coloring of a
graph to produce an new coloring. The vertices of the graph are
sorted according to a given permutation of the colors so that vertices
with the same color are recolored concurrently. There are two modes
of the recoloring procedure that are controlled by
RECOLORING_TYPE parameter. In asynchronous recoloring, the vertices
are colored using the same algorithm used for the original coloring;
the only difference is the ordering of the vertices, which is expected
to present less conflicts (and therefore is faster and leads to fewer
colors). In synchronous recoloring, each processor waits for its
neighboors to finish coloring the vertices of a given color before
starting to color the vertices of the next color. Using a simple first
fit color allocation policy, the algorithm guarantees that no
conflicts will be generated and that the number of colors will not
increase. The order in which the colors are considers is given by the
RECOLORING_PERMUTATION parameter. The forward order processes the
colors in increasing value of the color identifier; while the reverse
order processes them in the opposite order. The non-decreasing order
processes the colors so that the most used color in the graph is
colored last; while the non-increasing order is the opposite
order. The number of times the recoloring procedure is applied is
controlled by the RECOLORING_NUM_OF_ITERATIONS parameter (setting it
to zero disables recoloring).
<br>&nbsp;
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<!--
<tr>
<td VALIGN=TOP><b>Color_Method String:</b></td>
<td><b> </b></td>
</tr>
-->
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; See <a href="ug_color.html">Coloring Algorithms</a>.</td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td NOSAVE>
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_F
N</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_F
N</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a></b>
</td>
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_util.html">Next:&nbsp;
Data Services and Utilities</a> |&nbsp; <a href="ug_color.html">Previous:&nbsp; Coloring Algorithms</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

183
thirdParty/Zoltan/docs/ug_html/ug_cpp.html vendored Normal file
View File

@ -0,0 +1,183 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<TITLE>Zoltan User's Guide: C++ Interface</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_fortran.html">Next</a>&nbsp; |&nbsp; <a href="ug_usage.html">Previous</a></i></b></div>
<H2>
<A NAME="cpp ug"></A>C++ Interface</H2>
The C++ interface to the Zoltan library is contained in the header files
listed below.
Each header file defines one class. Each class represents a Zoltan
data structure and the functions that operate on that data structure.
The class methods in the header files call functions in the Zoltan C library.
So to use the C++ interface from your application, include
the appropriate header file and link with the Zoltan C library.
<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
<TR> <TH>header file</TH> <TH>class</TH></TR>
<TR> <TD><I>include/zoltan_cpp.h</I></TD>
<TD><B>Zoltan</B>, representing a
<a href="ug_interface_init.html">load balancing</a> instance</TD>
<TR> <TD><I>Utilities/Communication/zoltan_comm_cpp.h</I></TD>
<TD><B>Zoltan_Comm</B>, representing an
<a href="ug_util_comm.html">unstructured communication</a> instance </TD>
</TR>
<TR> <TD><I>Utilities/DDirectory/zoltan_dd_cpp.h</I></TD>
<TD><B>Zoltan_DD</B>, representing a
<a href="ug_util_dd.html">distributed directory</a> instance </TD>
</TR>
<TR> <TD><I>Utilities/Timer/zoltan_timer_cpp.h</I></TD>
<TD><B>Zoltan_Timer</B>, representing a timer instance </TD>
</TR>
</TABLE>
<p>
More detailed information about the interface may be found in the
<a href="../dev_html/dev_cpp.html">Zoltan Developer's Guide</a>.
<p>
Simple examples of the use of the interface may be found in the
<I>examples/CPP</I> directory. A more complete example is the
test driver <a href="../dev_html/dev_driver.html">zCPPdrive</a>. The
source code for this test driver is in the <I>driver</I> directory.
<p>
A note on declaring application registered query functions from a
C++ application may be found in the section titled
<a href="ug_query.html">Application-Registered Query Functions</a>.
<p>
Two peculiarities of the wrapping of Zoltan with C++ classes are
mentioned here:
<ol>
<li>
You must call the C language function
<a href="ug_interface_init.html#Zoltan_Initialize"><I>Zoltan_Initialize</I> </a>
before using the C++ interface to the Zoltan library. This function should only
be called once. Due to design choices,
the C++ interface maintains no global state that is
independent of any instantiated objects, so it does not know if the
function has been called or not. Therefore, the C++ wrappers do not call
<a href="ug_interface_init.html#Zoltan_Initialize"><I>Zoltan_Initialize</I> </a>
for you.
<li>
It is preferable to allocate <B>Zoltan</B> objects dynamically so you can
explicitly delete them before your application exits.
(<B>Zoltan</B> objects allocated instead on the stack will be deleted
automatically at the completion of the scope in which they were created.)
The reason is that the <B>Zoltan</B>
destructor calls Zoltan_Destroy(), which makes an MPI call to free
the communicator in use by the <B>Zoltan</B> object. However the
MPI destructor may have been called before the <B>Zoltan</B>
destructor. In this case you
would receive an error while your application is exiting.
</ol>
This second point is illustrated in the good and bad example below.
<p>
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR>
<TD><A NAME="c++ item 1"></A>
<TT>int main(int argc, char *argv[])</tt><br>
<TT>{</tt><br>
<TT>&nbsp;MPI::Init(argc, argv);</tt><br>
<TT>&nbsp;int rank = MPI::COMM_WORLD.Get_rank();</tt><br>
<TT>&nbsp;int size = MPI::COMM_WORLD.Get_size();</tt><br><br>
<TT>&nbsp;//<I>Initialize the Zoltan library with a C language call</I></TT><br>
<TT>&nbsp;float version;</TT><br>
<TT>&nbsp;Zoltan_Initialize</A>(argc, argv, &version);</TT><br><br>
<TT>&nbsp;//<I>Dynamically create Zoltan object.</I></tt><br>
<TT>&nbsp;Zoltan *zz = new Zoltan(MPI::COMM_WORLD);</tt><br>
<TT>&nbsp;zz->Set_Param("LB_METHOD", "RCB");</tt><br><br>
<TT>&nbsp;//<I>Several lines of code would follow, working with zz</I></tt><br><br>
<TT>&nbsp;//<I>Explicitly delete the Zoltan object</I></tt><br>
<TT>&nbsp;delete zz;</tt><br>
<TT>&nbsp;MPI::Finalize();</tt><br>
<TT>&nbsp;}</tt><br>
</TR>
<CAPTION ALIGN=BOTTOM><I>Good example, Zoltan object is dynamically allocated
and explicity deleted before exit.</I></CAPTION>
</TABLE></CENTER>
<br>
<br>
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR>
<TD><A NAME="c++ item 2"></A>
<TT>int main(int argc, char *argv[])</tt><br>
<TT>{</tt><br>
<TT>Zoltan zz;</tt><br><br>
<TT>&nbsp;MPI::Init(argc, argv);</tt><br>
<TT>&nbsp;int rank = MPI::COMM_WORLD.Get_rank();</tt><br>
<TT>&nbsp;int size = MPI::COMM_WORLD.Get_size();</tt><br><br>
<TT>&nbsp;//<I>Initialize the Zoltan library with a C language call</I></TT><br>
<TT>&nbsp;float version;</TT><br>
<TT>&nbsp;Zoltan_Initialize</A>(argc, argv, &version);</TT><br><br>
<TT>&nbsp;zz.Set_Param("LB_METHOD", "RCB");</tt><br><br>
<TT>&nbsp;//<I>Several lines of code would follow, working with zz</I></tt><br><br>
<TT>&nbsp;MPI::Finalize();</tt><br>
<TT>&nbsp;}</tt><br>
</TR>
<CAPTION ALIGN=BOTTOM><I>Bad example, the MPI destructor may execute before the
Zoltan destructor at process exit.</I></CAPTION>
</TABLE></CENTER>
<br>
<br>
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_fortran.html">Next:&nbsp;Fortran Interface</A>&nbsp;
|&nbsp; <A HREF="ug_usage.html">Previous:&nbsp;Zoltan Usage</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

73
thirdParty/Zoltan/docs/ug_html/ug_examples.html vendored Normal file
View File

@ -0,0 +1,73 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<TITLE>Zoltan User's Guide: Examples</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_examples_init.html">Next</a>&nbsp; |&nbsp; <a href="ug_util_dd.html">Previous</a></i></b></div>
<H2>
<A NAME="Examples of Library Usage"></A>Examples of Zoltan Usage</H2>
Examples for each part of the Zoltan library are provided:
<BLOCKQUOTE><A HREF="ug_examples_init.html">General use of Zoltan</A>
<BR><A HREF="ug_examples_lb.html">Load-balancing calling sequence</A>
<BR><A HREF="ug_examples_mig.html">Data migration calling sequences</A>
<BR><A HREF="ug_examples_query.html">Query functions for a simple application</A></BLOCKQUOTE>
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_examples_init.html">Next:&nbsp; General Usage Example</A>&nbsp;
|&nbsp; <A HREF="ug_util_dd.html">Previous:&nbsp; Distributed Data Directories</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

162
thirdParty/Zoltan/docs/ug_html/ug_examples_init.html vendored Normal file
View File

@ -0,0 +1,162 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<TITLE>Zoltan User's Guide: General Usage Examples</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_examples_lb.html">Next</a>&nbsp; |&nbsp; <a href="ug_examples.html">Previous</a></i></b></div>
<H2>
<A NAME="Initialization Example"></A>General Usage Example</H2>
An example of general Zoltan usage is included below. This is a C language
example. Similar C++ examples may be found in the <I>examples</I> directory.
<p>
In this example, <B><A HREF="ug_interface_init.html#Zoltan_Initialize">Zoltan_Initialize</A></B>
is called using the <I>argc</I> and <I>argv</I> arguments to the main program.
Then a pointer to a Zoltan structure is returned by the call to
<B><A HREF="ug_interface_init.html#Zoltan_Create">Zoltan_Create</A></B>.
In this example, all processors will be used by Zoltan, as
<B>MPI_COMM_WORLD</B> is passed to
<b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>
as the communicator.
<p>
Several application query functions are then registered with Zoltan through
calls to <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>.
Parameters are set through calls to
<b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
The application then performs in computations,
including making calls to Zoltan functions and utilities.
<p>
Before its execution ends, the application frees memory used by Zoltan by
calling
<b><a href="ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</a></b>.
<BR>&nbsp;
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR NOSAVE>
<TD NOSAVE><A NAME="Init Example Fig"></A><TT>/* Initialize the Zoltan library
*/</TT>&nbsp;
<BR><TT>struct Zoltan_Struct *zz;</TT>&nbsp;
<BR><TT>float version;</TT>&nbsp;
<BR><TT>...</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Initialize">Zoltan_Initialize</A>(argc,
argv, &amp;version);</TT>&nbsp;&nbsp;
<BR><TT>zz = <A HREF="ug_interface_init.html#Zoltan_Create">Zoltan_Create</A>(MPI_COMM_WORLD);</TT>
<p><tt>/* <i>Register query functions.</i> */</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz, <a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN_TYPE</a>, </tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_return_dimension, NULL);</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz, <a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_return_coords, NULL);</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz, <a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_return_num_node, NULL);</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz, <a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_return_owned_nodes, NULL);</tt>
<p><tt>/* <i>Set some Zoltan parameters.</i> */</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz, "debug_level", "4");</tt>
<p><tt>/* <i>Perform application computations, call Zoltan, etc.</i> */</tt>
<br><tt>...</tt>
<p><tt>/* <i>Free Zoltan data structure before ending application.</i> */</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</a> (&amp;zz);&nbsp;</tt>
</TD>
</TR>
<CAPTION ALIGN=BOTTOM><I>Typical calling sequence for general usage of
the Zoltan library.</I></CAPTION>
</TABLE></CENTER>
&nbsp;
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR NOSAVE>
<TD NOSAVE><TT>! Initialize the Zoltan library</TT>&nbsp;
<BR><TT>type(Zoltan_Struct), pointer :: zz</TT>&nbsp;
<BR><TT>real(Zoltan_FLOAT) version</TT>&nbsp;
<BR><TT>integer(Zoltan_INT) ierr</TT>&nbsp;
<BR><TT>...</TT>&nbsp;
<BR><TT>ierr = <A HREF="ug_interface_init.html#Zoltan_Initialize">Zoltan_Initialize</A>(version)
! without argc and argv</TT>&nbsp;&nbsp;
<BR><TT>zz => <A HREF="ug_interface_init.html#Zoltan_Create">Zoltan_Create</A>(MPI_COMM_WORLD)</TT>
<p><tt>! <i>Register load-balancing query functions.</i></tt>
<br><tt>! omit data = C NULL</tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN_TYPE</a>, user_return_dimension)</tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN_TYPE</a>, user_return_coords)</tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN_TYPE</a>, user_return_num_node)</tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN_TYPE</a>, user_return_owned_nodes)</tt>
<p><tt>! <i>Set some Zoltan parameters.</i></tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz, "debug_level", "4")</tt>
<p><tt>! <i>Perform application computations, call Zoltan, etc.</i></tt>
<br><tt>...</tt>
<p><tt>! <i>Free Zoltan data structure before ending application.</i></tt>
<br><tt>call <a href="ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</a>(zz)&nbsp;</tt>
</TD>
</TR>
<CAPTION ALIGN=BOTTOM><I>Fortran version of general usage
example.</I></CAPTION>
</TABLE></CENTER>
&nbsp;
<P>
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_examples_lb.html">Next:&nbsp; Load-Balancing Example</A>&nbsp;
|&nbsp; <A HREF="ug_examples.html">Previous:&nbsp; Examples of Library
Usage</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

173
thirdParty/Zoltan/docs/ug_html/ug_examples_lb.html vendored Normal file
View File

@ -0,0 +1,173 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Load-Balancing Examples</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_examples_mig.html">Next</a>&nbsp; |&nbsp; <a href="ug_examples_init.html">Previous</a></i></b></div>
<h2>
<a NAME="Load-Balancing Example"></a>Load-Balancing Example</h2>
An example of the typical calling sequence for load balancing using Zoltan
in a finite element application is shown in the <a href="#LB Example Fig">figure</a>
below. An application first selects a load-balancing algorithm
by setting the <a href="ug_alg.html#LB_METHOD"><i>LB_METHOD</i></a> parameter
with
<b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
Next, other parameter values are set by calls to
<b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
After some computation, load balancing is invoked by calling <b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>.
The results of the load balancing include the number of nodes to be imported
and exported to the processor, lists of global and local IDs of the imported
and exported nodes, and source and destination processors of the imported
and exported nodes. A returned argument of <b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
is tested to see whether the new decomposition differs from the old one.
If the decompositions differ, some sort of data migration is needed to
establish the new decomposition; the details of migration are not shown
in this <a href="#LB Example Fig">figure</a> but will be addressed in the
<a href="ug_examples_mig.html">migration
examples</a>. After the data migration is completed, the arrays of information
about imported and exported nodes returned by <b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
are freed by a call to <b><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
<br>&nbsp;
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr>
<td><a NAME="LB Example Fig"></a><tt>char *lb_method;</tt>
<br><tt>int new, num_imp, num_exp, *imp_procs, *exp_procs;</tt>
<br><tt>int *imp_to_part, *exp_to_part;</tt>
<br><tt>int num_gid_entries, num_lid_entries;</tt>
<br><tt><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a>&nbsp;imp_global_ids,
exp_global_ids;</tt>
<br><tt><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a>
imp_local_ids, exp_local_ids;</tt>
<p><tt>/* <i>Set load-balancing method.</i> */</tt>
<br><tt>read_load_balancing_info_from_input_file(&amp;lb_method);</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"LB_METHOD", lb_method);</tt>
<p><tt>/* <i>Reset some load-balancing parameters.</i> */</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"RCB_Reuse", "TRUE");</tt>
<p><tt>/* <i>Perform computations</i> */</tt>
<br><tt>...</tt>
<br><tt>/* <i>Perform load balancing</i> */</tt>
<br><tt><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a>(zz,&amp;new,&amp;num_gid_entries,&amp;num_lid_entries,</tt>
<br><tt>&nbsp;&nbsp;&nbsp; &amp;num_imp,&amp;imp_global_ids,&amp;imp_local_ids,&amp;imp_procs,&amp;imp_to_part,</tt>
<br><tt>&nbsp;&nbsp;&nbsp; &amp;num_exp,&amp;exp_global_ids,&amp;exp_local_ids,&amp;exp_procs,&amp;exp_to_part);&nbsp;</tt>
<br><tt>if (new)</tt>
<br><tt>&nbsp; perform_data_migration(...);</tt>
<p><tt>/* <i>Free memory allocated for load-balancing results by Zoltan library</i>
*/</tt>
<br><tt><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a>(&amp;imp_global_ids,
&amp;imp_local_ids, &amp;imp_procs, &amp;imp_to_part);</tt>
<br><tt><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a>(&amp;exp_global_ids,
&amp;exp_local_ids, &amp;exp_procs, &amp;exp_to_part);</tt>
<br><tt>...</tt>
</td>
</tr>
<caption ALIGN=BOTTOM><i>Typical calling sequence for performing load balancing
with the Zoltan library.</i></caption>
</table></center>
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr>
<td><tt>character(len=3) lb_method</tt>
<br><tt>logical new</tt>
<br><tt>integer(Zoltan_INT) num_imp, num_exp</tt>
<br><tt>integer(Zoltan_INT)&nbsp;num_gid_entries, num_lid_entries&nbsp;</tt>
<br><tt>integer(Zoltan_INT), pointer :: imp_procs(:), exp_procs(:)</tt>
<br><tt>integer(Zoltan_INT), pointer :: imp_global_ids(:), exp_global_ids(:)
! global IDs</tt>
<br><tt>integer(Zoltan_INT), pointer :: imp_local_ids(:), exp_local_ids(:)
! local IDs</tt>
<br><tt>integer(Zoltan_INT) ierr</tt>
<p><tt>! <i>Set load-balancing method.</i></tt>
<br><tt>lb_method = "RCB"</tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz, "LB_METHOD",
lb_method)</tt>
<p><tt>! <i>Reset some load-balancing parameters</i></tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"RCB_Reuse", "TRUE")</tt>
<p><tt>! <i>Perform computations</i></tt>
<br><tt>...</tt>
<br><tt>! <i>Perform load balancing</i></tt>
<br><tt>ierr = <a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a>(zz,new,num_gid_entries,num_lid_entries,&nbsp;&amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; num_imp,imp_global_ids,imp_local_ids,
&amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; imp_procs,imp_to_part, &amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; num_exp,exp_global_ids,exp_local_ids, &amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; exp_procs,exp_to_part)&nbsp;</tt>
<br><tt>if (new) then</tt>
<br><tt>&nbsp; perform_data_migration(...)</tt>
<br><tt>endif</tt>
<p><tt>! <i>Free memory allocated for load-balancing results by Zoltan library</i></tt>
<br><tt>ierr = <a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a>(imp_global_ids, imp_local_ids, imp_procs, imp_to_part);</tt>
<br><tt>ierr = <a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a>(exp_global_ids, exp_local_ids, exp_procs, exp_to_part);</tt>
<br><tt>...</tt></td>
</tr>
<caption ALIGN=BOTTOM><i>Fortran version of the load-balancing example.</i></caption>
</table></center>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; |
<a href="ug_examples_mig.html">Next:&nbsp;
Migration Examples</a>&nbsp; |&nbsp; <a href="ug_examples_init.html">Previous:&nbsp;
General Usage Example</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

246
thirdParty/Zoltan/docs/ug_html/ug_examples_mig.html vendored Normal file
View File

@ -0,0 +1,246 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<TITLE>Zoltan User's Guide: Migration Examples</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_examples_query.html">Next</a>&nbsp; |&nbsp; <a href="ug_examples_lb.html">Previous</a></i></b></div>
<H2>
<A NAME="Migration Example"></A>Migration Examples</H2>
Data migration using Zoltan's migration tools can be accomplished
in two different ways:
<BLOCKQUOTE><A HREF="#Auto-migration example">auto-migration</A>, or
<BR><A HREF="#User-guided Migration Example">user-guided migration</A>.</BLOCKQUOTE>
The choice of migration method depends upon the complexity of the application's
data. For some applications, only the objects used in balancing must be
migrated; no auxiliary data structures must be moved. Particle simulations
are examples of such applications; load balancing is based on the number
of particles per processor, and only the particles and their data must
be moved to establish the new decomposition. For such applications, Zoltan's
auto-migration tools can be used. Other applications, such as finite element
methods, perform load balancing on, say, the nodes of the finite element
mesh, but nodes that are moved to new processors also need to have their
connected elements moved to the new processors, and migrated elements may
also need "ghost" nodes (i.e., copies of nodes assigned to other processors)
to satisfy their connectivity requirements on the new processor. This complex
data migration requires a more user-controlled approach to data migration
than the auto-migration capabilities Zoltan can provide.
<BR>&nbsp;
<H2>
<A NAME="Auto-migration example"></A>Auto-Migration Example</H2>
In the <A HREF="#Auto-Migration Example Fig">figure</A> below, an example
of the load-balancing calling sequence for a particle simulation using
Zoltan's auto-migration tools is shown.
The application
requests auto-migration by turning on the <B>AUTO_MIGRATE</B> option
through a call to <B><A HREF="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</A></B>
and registers functions to pack and unpack a particle's data. During the
call to <B><A HREF="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</A></B>,
Zoltan computes the new decomposition and, using calls
to the packing and unpacking query functions, automatically migrates particles
to their new processors. The application then frees the arrays returned
by <B><A HREF="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</A></B> and
can continue computation without having to perform any additional operations
for data migration.
<BR>&nbsp;
<BR>&nbsp;
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR>
<TD><A NAME="Auto-Migration Example Fig"></A>
<TT>/* <I>Tell Zoltan to automatically migrate data for the application.</I>
*/</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</A>(zz, "AUTO_MIGRATE",
"TRUE");</TT>&nbsp;
<P><TT>/* <I>Register additional functions for packing and unpacking data</I>
*/</TT>&nbsp;
<BR><TT>/* <I>by migration tools. </I>*/</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</A>(zz, <A HREF="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN_TYPE</A>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_return_particle_data_size, NULL);</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</A>(zz, <A HREF="ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN_TYPE</A>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_pack_particle_data, NULL);</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</A>(zz, <A HREF="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN_TYPE</A>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_unpack_particle_data, NULL);</TT>&nbsp;
<BR><TT>...</TT>&nbsp;
<BR><TT>/* <I>Perform computations</I> */</TT>&nbsp;
<BR><TT>...</TT>&nbsp;
<BR><TT>/* <I>Perform load balancing AND automatic data migration!</I>
*/</TT>&nbsp;
<BR><TT><A HREF="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</A>(zz,&amp;new,&amp;num_gid_entries,&amp;num_lid_entries,</tt>
<br><tt>&nbsp;&nbsp;&nbsp; &amp;num_imp,&amp;imp_global_ids,&amp;imp_local_ids,&amp;imp_procs,&amp;imp_to_part,</TT>
<BR><TT>&nbsp;&nbsp;&nbsp; &amp;num_exp,&amp;exp_global_ids,&amp;exp_local_ids,&amp;exp_procs,&amp;exp_to_part);</TT>&nbsp;
<P><TT>/* <I>Free memory allocated for load-balancing results by Zoltan </I>
*/</TT>&nbsp;
<BR><TT><A HREF="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</A>(&amp;imp_global_ids, &amp;imp_local_ids, &amp;imp_procs, &amp;imp_to_part);</TT>
<BR><TT><A HREF="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</A>(&amp;exp_global_ids, &amp;exp_local_ids, &amp;exp_procs, &amp;exp_to_part);</TT>
<BR><TT>...</TT></TD>
</TR>
<CAPTION ALIGN=BOTTOM><I>Typical calling sequence for using the migration
tools' auto-migration capability with the dynamic load-balancing tools.</I></CAPTION>
</TABLE></CENTER>
&nbsp;
<H2>
<A NAME="User-guided Migration Example"></A>User-Guided Migration Example</H2>
In the following <A HREF="#User-guided Migration Example Fig">figure</A>,
an example of user-guided migration using Zoltan's migration tools
for a finite element application is shown. Several migration steps are
needed to completely rebuild the application's data structures for the
new decomposition. On each processor, newly imported nodes need copies
of elements containing those nodes. Newly imported elements, then, need
copies of "ghost" nodes, nodes that are in the element but are assigned
to other processors. Each of these entities (nodes, elements, and ghost
nodes) can be migrated in separate migration steps using the functions
provided in the migration tools. First, the assignment of nodes to
processors returned by <B><A HREF="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</A></B>
is established. Query functions that pack and unpack nodes are registered
and <B><A HREF="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</A></B>
is called using the nodal decomposition returned from <B><A HREF="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</A></B>.
<B><A HREF="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</A></B>
packs the nodes to be exported, sends them to other processors, and unpacks
nodes received by a processor. The packing routine <I>migrate_node_pack</I>
includes with each node a list of the element IDs for elements containing
that node. The unpacking routine <I>migrate_node_unpack</I> examines the
list of element IDs and builds a list of requests for elements the processor
needs but does not already store. At the end of the nodal migration, each
processor has a list of element IDs for elements that it needs to support
imported nodes but does not already store. Through a call to <B><A HREF="ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</A></B>,
each processor computes the list of elements it has to send to other processors
to satisfy their element requests. Packing and unpacking routines for elements
are registered, and <B><A HREF="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</A></B>
is again used to move element data to new processors. Requests for ghost
nodes can be built within the element packing and unpacking routines, and
calls to <B><A HREF="ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</A></B>
and <B><A HREF="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</A></B>,
with node packing and unpacking, satisfy requests for ghost nodes. In all
three phases of migration, the migration tools handle communication;
the application is responsible only for packing and unpacking data and
for building the appropriate request lists.
<BR>&nbsp;
<BR>&nbsp;
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR NOSAVE>
<TD NOSAVE><A NAME="User-guided Migration Example Fig"></A><TT>/* <I>Assume
Zoltan returns a decomposition of the</I> */</TT>&nbsp;
<BR><TT>/* <I>nodes of a finite element mesh.</I> */</TT>&nbsp;
<BR><TT><A HREF="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</A>(zz,&amp;new,&amp;num_gid_entries,&amp;num_lid_entries,</tt>
<br><tt>&nbsp;&nbsp;&nbsp; &amp;num_imp,&amp;imp_global_ids,&amp;imp_local_ids,&amp;imp_procs,&amp;imp_to_part,</TT>
<BR><TT>&nbsp;&nbsp;&nbsp; &amp;num_exp,&amp;exp_global_ids,&amp;exp_local_ids,&amp;exp_procs,&amp;exp_to_part);</TT>
<P><TT>/* <I>Migrate the nodes as directed by the results of Zoltan_LB_Partition.</I>
*/</TT>
<BR><TT>/* <I>While unpacking nodes, build list of requests for elements
needed</I> */</TT>
<BR><TT>/* <I>to support the imported nodes.</I>*/</TT>
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</A>(zz, <A HREF="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN_TYPE</A>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) migrate_node_size, NULL);</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</A>(zz, <A HREF="ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN_TYPE</A>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) migrate_pack_node, NULL);</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</A>(zz, <A HREF="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN_TYPE</A>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) migrate_unpack_node, NULL);</TT>&nbsp;
<BR><TT><A HREF="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</A>(zz,num_import,imp_global_ids,imp_local_ids,imp_procs,imp_to_part,</TT>
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; num_export,exp_global_ids,exp_local_ids,exp_procs,exp_to_part);</TT>
<P><TT>/* <I>Prepare for migration of requested elements.</I> */</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</A>(zz, <A HREF="ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN_TYPE</A>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) migrate_pack_element, NULL);</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</A>(zz, <A HREF="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN_TYPE</A>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) migrate_unpack_element, NULL);</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</A>(zz, <A HREF="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN_TYPE</A>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) migrate_element_size, NULL);</TT>&nbsp;
<P><TT>/* <I>From the request lists, a processor knows which elements it
needs</I> */</TT>&nbsp;
<BR><TT>/* <I>to support the imported nodes; it must compute which elements
to</I> */</TT>&nbsp;
<BR><TT>/* <I>send to other processors. </I>*/</TT>&nbsp;
<BR><TT><A HREF="ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</A>(zz,
Num_Elt_Requests, Elt_Requests_Global_IDs,&nbsp;</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Elt_Requests_Local_IDs,
Elt_Requests_Procs, Elt_Requests_to_Part,</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &amp;num_tmp_exp,
&amp;tmp_exp_global_ids,&nbsp;</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &amp;tmp_exp_local_ids,
&amp;tmp_exp_procs, &amp;tmp_exp_to_part);&nbsp;</TT>&nbsp;
<P><TT>/* <I>Processor now knows which elements to send to other processors.</I>
*/</TT>&nbsp;
<BR><TT>/* <I>Send the requested elements. While unpacking elements, build
</I>*/</TT>&nbsp;
<BR><TT>/* <I>request lists for "ghost" nodes needed by the imported elements.</I>
*/</TT>&nbsp;
<BR><TT><A HREF="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</A>(zz,
Num_Elt_Requests, Elt_Requests_Global_IDs,&nbsp;</TT>&nbsp;
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Elt_Requests_Local_IDs, Elt_Requests_Procs, Elt_Request_to_Part,</TT>
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; num_tmp_exp_objs, tmp_exp_global_ids,&nbsp;</TT>
<BR><TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; tmp_exp_local_ids, tmp_exp_procs, tmp_exp_to_part);</TT>
<P><TT>/* <I>Repeat process for "ghost" nodes.</I> */</TT>&nbsp;
<BR><TT>...</TT></TD>
</TR>
<CAPTION ALIGN=BOTTOM><I>Typical calling sequence for user-guided use of
the migration tools in Zoltan</I>.</CAPTION>
</TABLE></CENTER>
&nbsp;
<BR>
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_examples_query.html">Next:&nbsp; Query-Function Examples</A>&nbsp;
|&nbsp; <A HREF="ug_examples_lb.html">Previous:&nbsp; Load-Balancing Example</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>

610
thirdParty/Zoltan/docs/ug_html/ug_examples_query.html vendored Normal file
View File

@ -0,0 +1,610 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Query-Functon Examples</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_release.html">Next</a>&nbsp; |&nbsp; <a href="ug_examples_mig.html">Previous</a></i></b></div>
<!-------------------------------------------------------------------------->
<h2>
<a NAME="Query-Function Example"></a>Query-Function Examples</h2>
Examples of query functions provided by a simple application are included
below.&nbsp; The general-interface examples include a simple implementation
of <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a> </b>and <b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
query functions and variants of the simple implementation that exploit
local identifiers and data pointers.&nbsp; Migration examples for packing
and unpacking objects are also included.&nbsp;&nbsp; Robust error checking
is not included in the routines; application developers should include
more explicit error checking in their query functions.
<ul><a href="#lb_query_example">General Interface Examples</a>
<ul><a href="#basic_query_example">Basic example</a>
<br><a href="#data_ptr_query_example">User-defined data pointer</a></ul>
<a href="#mig_query_example">Migration Examples</a>
<ul><a href="#mig_pack_example">Packing and unpacking functions</a></ul>
</ul>
All the examples use a mesh data structure consisting of nodes in the mesh.&nbsp;
these nodes are the objects passed to Zoltan.&nbsp; A node is described by
its 3D coordinates and a global ID number that is unique across all processors.&nbsp;&nbsp;
The type definitions for the mesh and node data structures used in the
examples are included <a href="#query example data types">below</a>.
<!-------------------------------------------------------------------------->
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr>
<td><a NAME="query example data types"></a><tt>/*<i> Node data structure.</i>
*/</tt>
<br><tt>/* <i>A node consists of its 3D coordinates and</i> */</tt>
<br><tt>/* <i>an ID number that is unique across all processors.</i> */</tt>
<br><tt>struct Node_Type {&nbsp;</tt>
<br><tt>&nbsp; double Coordinates[3];&nbsp;</tt>
<br><tt>&nbsp; int Global_ID_Num;&nbsp;</tt>
<br><tt>};&nbsp;</tt>
<p><tt>/*<i> Mesh data structure.</i> */&nbsp;</tt>
<br><tt>/* <i>Mesh consists of an array of nodes and</i> */</tt>
<br><tt>/* <i>the number of nodes owned by the processor.</i> */</tt>
<br><tt>struct Mesh_Type {</tt>
<br><tt>&nbsp; struct Node_Type Nodes[MAX_NODES];&nbsp;</tt>
<br><tt>&nbsp; int Number_Owned;&nbsp;</tt>
<br><tt>};</tt></td>
</tr>
<caption ALIGN=BOTTOM><i>Data types for the query-function examples.</i></caption>
</table></center>
<!-------------------------------------------------------------------------->
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr>
<td><a NAME="query example Fortran data types"></a><tt>!<i> Node data structure.</i></tt>
<br><tt>! <i>A node consists of its 3D coordinates and</i></tt>
<br><tt>! <i>an ID number that is unique across all processors.</i></tt>
<br><tt>type Node_Type&nbsp;&nbsp;</tt>
<br><tt>&nbsp; real(Zoltan_DOUBLE) :: Coordinates(3)&nbsp;</tt>
<br><tt>&nbsp; integer(Zoltan_INT) :: Global_ID_Num&nbsp;</tt>
<br><tt>end type Node_Type</tt>
<br><tt>&nbsp;</tt>
<p><tt>!<i> Mesh data structure.</i>&nbsp;</tt>
<br><tt>! <i>Mesh consists of an array of nodes and</i></tt>
<br><tt>! <i>the number of nodes owned by the processor.</i></tt>
<br><tt>type Mesh_Type&nbsp;</tt>
<br><tt>&nbsp; type(Node_Type) :: Nodes(MAX_NODES)&nbsp;</tt>
<br><tt>&nbsp; integer(Zoltan_INT) :: Number_Owned&nbsp;</tt>
<br><tt>end type Mesh_Type</tt>
<br>&nbsp;</td>
</tr>
<caption ALIGN=BOTTOM><i>Data types for the Fortran query-function examples.</i></caption>
</table></center>
<!-------------------------------------------------------------------------->
<h3>
<a NAME="lb_query_example"></a>General Interface Query Function Examples</h3>
In the following examples, <b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
and <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN </a></b>query functions
are implemented for an application using the mesh and node data structures
described <a href="#query example data types">above</a>.&nbsp;
The nodes are the objects passed to Zoltan.
<p>Through a call to <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>,
the function <i>user_return_owned_nodes</i> is registered as the <b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
query function.&nbsp; It returns&nbsp; global and local identifiers for
each node owned by a processor.
<p>The function <i>user_return_coords</i> is registered as a&nbsp; <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
query function.&nbsp; Given the global and local identifiers for a node,
this function returns the node's coordinates.&nbsp; All the examples exploit
the local identifier to quickly locate nodal data.&nbsp; If such an identifier
is not available in an application, a search using the global identifier
can be performed.
<p>The <a href="#basic_query_example">Basic Example</a> includes the simplest
implementation of the query routines.&nbsp; In the query routines, it uses
global application data structures and a local numbering scheme for the
local identifiers.&nbsp; The <a href="#data_ptr_query_example">User-Defined
Data Pointer Example</a> uses only local application data structures; this
model is useful if the application does not have global data structures
or if objects from more than one data structure are to be passed to Zoltan.&nbsp;
Differences between the latter example and the Basic Example are
shown in <font color="#FF0000">red</font>.
<h4>
<a NAME="basic_query_example"></a>Basic Example</h4>
In the simplest example, the query functions access the application data
through a global data structure (<i>Mesh</i>) representing the mesh.&nbsp;
In the calls to <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>,
no pointers to application data are registered with the query function
(i.e., the <i>data</i> pointer is not used).&nbsp;&nbsp; A node's local
identifier is an integer representing the index in the <i>Mesh.Nodes</i>
array of the node.&nbsp; The local identifier is set to the index's value
in<i> user_return_owned_nodes</i>.&nbsp; It is used to access the global
<i>Mesh.Nodes</i> array in <i>user_return_coords</i>.
<!-------------------------------------------------------------------------->
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr>
<td><a NAME="query example one"></a><tt>/* <i>in application's program
file</i> */&nbsp;</tt>
<br><tt>#include "zoltan.h"</tt>
<p><tt>/* <i>Declare a global Mesh data structure.</i> */</tt>
<br><tt>struct Mesh_Type Mesh;</tt>
<p><tt>main()&nbsp;</tt>
<br><tt>{&nbsp;</tt>
<br><tt>...&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>Indicate that local and global IDs are
one integer each. */</i></tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>", "1");</tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"<a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>", "1");</tt><tt></tt>
<p><tt>&nbsp;&nbsp;&nbsp; /* <i>Register query functions.</i>
*/</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>Do not register a data pointer with the
functions;</i> */</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>the global Mesh data structure will be
used.</i> */</tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN_TYPE</a>,&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(void (*)()) user_return_coords, NULL);&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN_TYPE</a>,&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(void (*)()) user_return_owned_nodes, NULL);&nbsp;&nbsp;</tt>
<br><tt>...&nbsp;</tt>
<br><tt>}&nbsp;</tt>
<p><tt>void user_return_owned_nodes(void *data,&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; int num_gid_entries, int num_lid_entries,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a>&nbsp;global_ids, <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a>&nbsp;local_ids,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; int wgt_dim, float *obj_wgts,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; int *ierr)&nbsp;</tt>
<br><tt>{&nbsp;</tt>
<br><tt>int i;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>return global node numbers as global_ids.</i>
*/&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>return index into Nodes array for local_ids.</i>
*/&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; for (i = 0; i &lt; Mesh.Number_Owned; i++){&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; global_ids[i*num_gid_entries]
= Mesh.Nodes[i].Global_ID_Num;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; local_ids[i*num_lid_entries]
= i;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; }&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; *ierr = ZOLTAN_OK;&nbsp;</tt>
<br><tt>}&nbsp;</tt>
<p><tt>void user_return_coords(void *data,&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; int num_gid_entries, int num_lid_entries,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a>&nbsp;global_id, <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> local_id,&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; double *geom_vec, int *ierr)&nbsp;</tt>
<br><tt>{&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>use local_id to index into the Nodes array.</i>
*/&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; geom_vec[0] = Mesh.Nodes[local_id[0]].Coordinates[0];&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; geom_vec[1] = Mesh.Nodes[local_id[0]].Coordinates[1];&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; geom_vec[2] = Mesh.Nodes[local_id[0]].Coordinates[2];&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; *ierr = ZOLTAN_OK;&nbsp;</tt>
<br><tt>}</tt></td>
</tr>
<caption ALIGN=BOTTOM><i>Example of general interface query functions (simplest
implementation).</i></caption>
</table></center>
<!-------------------------------------------------------------------------->
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr>
<td><a NAME="query Fortran example one"></a><tt>! <i>in application's program
file</i>&nbsp;</tt>
<p><tt>module Global_Mesh_Data</tt>
<br><tt>! <i>Declare a global Mesh data structure.</i></tt>
<br><tt>&nbsp;&nbsp; type(Mesh_Type) :: Mesh</tt>
<br><tt>end module</tt>
<p><tt>program query_example_1&nbsp;</tt>
<br><tt>use zoltan</tt>
<br><tt>...&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ! <i>Indicate that local and global IDs are
one integer each.&nbsp;</i></tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>", "1");</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"<a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>", "1");</tt><tt></tt>
<p><tt>&nbsp;&nbsp;&nbsp; ! <i>Register query functions.</i></tt>
<br><tt>&nbsp;&nbsp;&nbsp; ! <i>Do not register a data pointer with the
functions;</i></tt>
<br><tt>&nbsp;&nbsp;&nbsp; ! <i>the global Mesh data structure will be
used.</i></tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN_TYPE</a>,</tt>
<tt>user_return_coords)&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN_TYPE</a>,</tt>
<tt>user_return_owned_nodes)&nbsp;&nbsp;</tt>
<br><tt>...&nbsp;</tt>
<br><tt>end program&nbsp;</tt>
<p><tt>subroutine user_return_owned_nodes(data, &amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; num_gid_entries, num_lid_entries, &amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; global_ids, local_ids, wgt_dim, obj_wgts, ierr)&nbsp;</tt>
<br><tt>use zoltan&nbsp;</tt>
<br><tt>use Global_Mesh_Data&nbsp;</tt>
<br><tt>integer(Zoltan_INT) :: data(1) ! dummy declaration, do not use</tt>
<br><tt>integer(Zoltan_INT), intent(in)&nbsp;::&nbsp;num_gid_entries, num_lid_entries</tt>
<br><tt>integer(Zoltan_INT), intent(out) :: global_ids(*), local_ids(*)</tt>
<br><tt>integer(Zoltan_INT), intent(in) :: wgt_dim</tt>
<br><tt>real(Zoltan_FLOAT), intent(out) :: obj_wgts(*)</tt>
<br><tt>integer(Zoltan_INT), intent(out) :: ierr</tt>
<br><tt>integer i&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ! <i>return global node numbers as global_ids.</i>&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ! <i>return index into Nodes array for local_ids.</i>&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; do i = 1, Mesh%Number_Owned&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; global_ids(1+(i-1)*num_gid_entries) = &amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Mesh%Nodes(i)%Global_ID_Num&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; local_ids(1+(i-1)*num_lid_entries)
= i&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; end do&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = ZOLTAN_OK&nbsp;</tt>
<br><tt>end subroutine&nbsp;</tt>
<p><tt>subroutine user_return_coords(data, num_gid_entries, num_lid_entries,
&amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; global_id, local_id, geom_vec, ierr)&nbsp;</tt>
<br><tt>use zoltan&nbsp;</tt>
<br><tt>use Global_Mesh_Data&nbsp;</tt>
<br><tt>integer(Zoltan_INT) :: data(1) ! dummy declaration, do not use</tt>
<br><tt>integer(Zoltan_INT), intent(in)&nbsp;::&nbsp;num_gid_entries, num_lid_entries</tt>
<br><tt>integer(Zoltan_INT), intent(in) :: global_id(*), local_id(*)</tt>
<br><tt>real(Zoltan_DOUBLE), intent(out) :: geom_vec(*)</tt>
<br><tt>integer(Zoltan_INT), intent(out) :: ierr</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ! <i>use local_id to index into the Nodes array.</i>&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; geom_vec(1:3) = Mesh%Nodes(local_id(1))%Coordinates&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = ZOLTAN_OK&nbsp;</tt>
<br><tt>end subroutine</tt></td>
</tr>
<caption ALIGN=BOTTOM><i>Fortran example of general interface query functions
(simplest implementation).</i></caption>
</table></center>
<!-------------------------------------------------------------------------->
<h4>
<a NAME="data_ptr_query_example"></a>User-Defined Data Pointer Example</h4>
In this example, the address of a local mesh data structure is registered
with the query functions for use by those functions.&nbsp; This change
eliminates the need for a global mesh data structure in the application.&nbsp;
The address of the local data structure is included as an argument in calls
to <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>.&nbsp;
This address is then used in <i>user_return_owned_nodes</i> and <i>user_return_coords</i>
to provide data for these routines.&nbsp; It is cast to the <i><a href="#query example data types">Mesh_Type</a></i>
data type and accessed with local identifiers as in the <a href="#basic_query_example">Basic
Example</a>.&nbsp; Differences between this example and the <a href="#basic_query_example">Basic
Example</a> are shown in <font color="#FF0000">red</font>.
<p>This model is useful when the application does not have a global data
structure that can be accessed by the query functions.&nbsp; It can also
be used for operations on different data structures.&nbsp; For example,
if an application had more than one mesh, load balancing could be performed
separately on each mesh without having different query routines for each
mesh.&nbsp; Calls to <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
would define which mesh should be balanced, and the query routines would
access the mesh currently designated by the <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
calls.
<!-------------------------------------------------------------------------->
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr>
<td><a NAME="query example three"></a><tt>/* <i>in application's program
file</i> */</tt>
<br><tt>#include "zoltan.h"</tt>
<p><tt>main()</tt>
<br><tt>{</tt>
<br><tt><font color="#FF0000">/* <i>declare a local mesh data structure.</i>
*/</font></tt>
<br><tt><font color="#FF0000">struct Mesh_Type mesh;</font></tt>
<br><tt>...</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>Indicate that local and global IDs are
one integer each. */</i></tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>", "1");</tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"<a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>", "1");</tt><tt></tt>
<p><tt>&nbsp;&nbsp;&nbsp; /* <i>Register query functions.</i>
*/</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i><font color="#FF0000">Register the address
of mesh as the data pointer.</font></i> */</tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(void (*)()) user_return_coords, <font color="#FF0000">&amp;mesh</font>);&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(void (*)()) user_return_owned_nodes, <font color="#FF0000">&amp;mesh</font>);&nbsp;</tt>
<br><tt>...</tt>
<br><tt>}</tt>
<p><tt>void user_return_owned_nodes(void *data,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; int num_gid_entries, int num_lid_entries,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> global_ids, <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a>&nbsp;local_ids,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; int wgt_dim, float *obj_wgts,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; int *ierr)&nbsp;</tt>
<br><tt>{</tt>
<br><tt>int i;&nbsp;</tt>
<br><tt><font color="#FF0000">/* <i>cast data pointer to type Mesh_Type.</i>
*/</font></tt>
<br><tt><font color="#FF0000">struct Mesh_Type *ptr = (struct Mesh_Type
*) data;</font></tt>
<p><tt>&nbsp;&nbsp;&nbsp; /* <i>return global node numbers as global_ids.</i>
*/</tt>&nbsp;<tt>&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>return index into Nodes array for local_ids.</i>
*/</tt>
<br><tt>&nbsp;&nbsp;&nbsp; for (i = 0; i &lt; ptr->Number_Owned; i++)
{</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; global_ids[i*num_gid_entries]
= <font color="#FF0000">ptr->Nodes[i].Global_ID_Num</font>;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; local_ids[i*num_lid_entries]
= i;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; }</tt>
<br><tt>&nbsp;&nbsp;&nbsp; *ierr = ZOLTAN_OK;</tt>
<br><tt>}</tt>
<p><tt>void user_return_coords(void *data,&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; int num_gid_entries, int num_lid_entries,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> global_id, <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> local_id,&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; double *geom_vec, int *ierr)</tt>
<br><tt>{</tt>
<p><tt><font color="#FF0000">/* <i>cast data pointer to type Mesh_Type.</i>
*/</font></tt>
<br><tt><font color="#FF0000">struct Mesh_Type *ptr = (struct Mesh_Type
*) data;</font></tt>
<p><tt>&nbsp;&nbsp;&nbsp; /* <i>use local_id to address the requested node.</i>
*/</tt>
<br><tt>&nbsp;&nbsp;&nbsp; geom_vec[0] = <font color="#FF0000">ptr->Nodes[local_id[0]].Coordinates[0]</font>;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; geom_vec[1] = <font color="#FF0000">ptr->Nodes[local_id[0]].Coordinates[1]</font>;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; geom_vec[2] = <font color="#FF0000">ptr->Nodes[local_id[0]].Coordinates[2]</font>;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; *ierr = ZOLTAN_OK;</tt>
<br><tt>}</tt></td>
</tr>
<caption ALIGN=BOTTOM><i>Example of general interface query functions using
the application-defined data pointer.</i></caption>
</table></center>
<!-------------------------------------------------------------------------->
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr>
<td><a NAME="query Fortran example three"></a><tt>/* <i>included in file
zoltan_user_data.f90</i> */</tt>
<br><tt><font color="#FF0000">! <i>User defined data type as wrapper for
Mesh</i></font></tt>
<br><tt><font color="#FF0000">type Zoltan_User_Data_1</font></tt>
<br><tt><font color="#FF0000">&nbsp;&nbsp; type(Mesh_type), pointer ::
ptr</font></tt>
<br><tt><font color="#FF0000">end type Zoltan_User_Data_1</font></tt>
<p>
<hr WIDTH="100%"><tt>! <i>in application's program file</i>&nbsp;</tt>
<p><tt>program query_example_3&nbsp;</tt>
<br><tt>use zoltan</tt>
<br><tt><font color="#FF0000">!<i> declare a local mesh data structure
and a User_Data to point to it.</i></font></tt>
<br><tt><font color="#FF0000">type(Mesh_Type), target :: mesh</font></tt>
<br><tt><font color="#FF0000">type(Zoltan_User_Data_1) data</font></tt>
<br><tt>...&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ! <i>Indicate that local and global IDs are
one integer each.&nbsp;</i></tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>", "1");</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz,
"<a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>", "1");</tt><tt></tt>
<p><tt>&nbsp;&nbsp;&nbsp; ! <i>Register query functions.</i></tt>
<br><tt><font color="#FF0000">&nbsp;&nbsp;&nbsp; ! <i>Use the User_Data
variable to pass the mesh data
</i></font></tt>
<br><tt><font color="#FF0000">&nbsp;&nbsp;&nbsp; data%ptr => mesh</font></tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN_TYPE</a>,</tt>
<tt>user_return_coords<font color="#FF0000">, data</font>)&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;user_return_owned_nodes<font color="#FF0000">, data</font>)</tt>
<br><tt>...&nbsp;</tt>
<br><tt>end program&nbsp;</tt>
<p><tt>subroutine user_return_owned_nodes(data, &amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; num_gid_entries, num_lid_entries, &amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; global_ids, local_ids, wgt_dim, obj_wgts, ierr)&nbsp;</tt>
<br><tt>use zoltan&nbsp;</tt>
<br><tt><font color="#FF0000">type(Zoltan_User_Data_1) :: data</font></tt>
<br><tt>integer(Zoltan_INT), intent(in)&nbsp;::&nbsp;num_gid_entries, num_lid_entries</tt>
<br><tt>integer(Zoltan_INT), intent(out) :: global_ids(*), local_ids(*)</tt>
<br><tt>integer(Zoltan_INT), intent(in) :: wgt_dim</tt>
<br><tt>real(Zoltan_FLOAT), intent(out) :: obj_wgts(*)</tt>
<br><tt>integer(Zoltan_INT), intent(out) :: ierr</tt>
<br><tt>integer i&nbsp;</tt>
<br><tt><font color="#FF0000">type(Mesh_Type), pointer :: Mesh</font></tt>
<p><tt><font color="#FF0000">&nbsp;&nbsp; ! <i>extract the mesh from the
User_Data argument</i></font></tt>
<br><tt><font color="#FF0000">&nbsp;&nbsp;&nbsp; Mesh => data%ptr</font></tt>
<p><tt>&nbsp;&nbsp;&nbsp; ! <i>return global node numbers as global_ids.</i>&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ! <i>return index into Nodes array for local_ids.</i>&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; do i = 1, Mesh%Number_Owned&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; global_ids(1+(i-1)*num_gid_entries) = &amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Mesh%Nodes(i)%Global_ID_Num&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; local_ids(1+(i-1)*num_lid_entries)
= i&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; end do&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = ZOLTAN_OK&nbsp;</tt>
<br><tt>end subroutine&nbsp;</tt>
<p><tt>subroutine user_return_coords(data, global_id, local_id, &amp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp; geom_vec, ierr)&nbsp;</tt>
<br><tt>use zoltan&nbsp;</tt>
<br><tt><font color="#FF0000">type(Zoltan_User_Data_1) :: data</font></tt>
<br><tt>integer(Zoltan_INT), intent(in)&nbsp;::&nbsp;num_gid_entries, num_lid_entries</tt>
<br><tt>integer(Zoltan_INT), intent(in) :: global_id(*), local_id(*)</tt>
<br><tt>real(Zoltan_DOUBLE), intent(out) :: geom_vec(*)</tt>
<br><tt>integer(Zoltan_INT), intent(out) :: ierr</tt>
<br><tt><font color="#FF0000">type(Mesh_Type), pointer :: Mesh</font></tt>
<p><tt><font color="#FF0000">&nbsp;&nbsp; ! <i>extract the mesh from the
User_Data argument</i></font></tt>
<br><tt><font color="#FF0000">&nbsp;&nbsp;&nbsp; Mesh => data%ptr</font></tt>
<p><tt>&nbsp;&nbsp;&nbsp; ! <i>use local_id to index into the Nodes array.</i>&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; geom_vec(1:3) = Mesh%Nodes(local_id(1))%Coordinates&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; ierr = ZOLTAN_OK&nbsp;</tt>
<br><tt>end subroutine</tt></td>
</tr>
<caption ALIGN=BOTTOM><i>Fortran example of general interface query functions
using the application-defined data pointer.</i></caption>
</table></center>
<!-------------------------------------------------------------------------->
<h3>
<a NAME="mig_query_example"></a>Migration Examples</h3>
<h4>
<a NAME="mig_pack_example"></a>Packing and Unpacking Data</h4>
Simple migration query functions for the <a href="#basic_query_example">Basic
Example</a> are included<a href="#query example four"> below</a>.&nbsp;
These functions are used by the migration tools to move nodes among the
processors.&nbsp; The functions <i>user_size_node</i>, <i>user_pack_node</i>,
and <i>user_unpack_node</i> are registered through calls to <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>.&nbsp;
Query function <i>user_size_node</i> returns the size (in bytes) of data
representing a single node.&nbsp; Query function <i>user_pack_node</i>
copies a given node's data into the communication buffer<i> buf</i>.&nbsp;
Query function <i>user_unpack_node</i> copies a data for one node from
the communication buffer <i>buf</i> into the <i>Mesh.Nodes</i> array on
its new processor.
<p>These query routines are simple because the application does not dynamically
allocate memory for each node.&nbsp; Such dynamic allocation would have
to be accounted for in the <a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN</a>,
<a href="ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN</a>,
and <a href="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN</a> routines.&nbsp;
<br>&nbsp;
<center><table BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<tr>
<td><a NAME="query example four"></a><tt>main()&nbsp;</tt>
<br><tt>{&nbsp;</tt>
<br><tt>...&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>Register migration query functions.</i>
*/</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>Do not register a data pointer with the
functions;</i> */</tt>
<br><tt>&nbsp;&nbsp;&nbsp; /* <i>the global Mesh data structure will be
used.</i> */</tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(void (*)()) user_size_node, NULL);&nbsp;&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(void (*)()) user_pack_node, NULL);&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(void (*)()) user_unpack_node, NULL);&nbsp;&nbsp;</tt>
<br><tt>...&nbsp;</tt>
<br><tt>}&nbsp;</tt>
<p><tt>int user_size_node(void *data, </tt>
<br><tt>&nbsp;&nbsp;&nbsp; int num_gid_entries, int num_lid_entries,</tt>
<br><tt>&nbsp;&nbsp;&nbsp; <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> global_id, <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> local_id, int *ierr)</tt>
<br><tt>{</tt>
<br><tt>/* <i>Return the size of data associated with one node.</i> */</tt>
<br><tt>/* <i>This case is simple because all nodes have the same size.</i> */</tt>
<br><tt>&nbsp;&nbsp;&nbsp; *ierr = ZOLTAN_OK;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; return(sizeof(struct Node_Type));</tt>
<br><tt>}</tt>
<p><tt>void user_pack_node(void *data, </tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;
int num_gid_entries, int num_lid_entries,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> global_id, <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> local_id,&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;
int dest_proc, int size, char *buf, int *ierr)&nbsp;</tt>
<br><tt>{</tt>
<br><tt>/* Copy<i> the specified node's data into buffer buf.</i> */</tt>
<br><tt>struct Node_Type *node_buf = (struct Node_Type *) buf;</tt>
<p><tt>&nbsp;&nbsp;&nbsp; *ierr = ZOLTAN_OK;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; node_buf->Coordinates[0] = Mesh.Nodes[local_id[0]].Coordinates[0];</tt>
<br><tt>&nbsp;&nbsp;&nbsp; node_buf->Coordinates[1] = Mesh.Nodes[local_id[0]].Coordinates[1];</tt>
<br><tt>&nbsp;&nbsp;&nbsp; node_buf->Coordinates[2] = Mesh.Nodes[local_id[0]].Coordinates[2];</tt>
<br><tt>&nbsp;&nbsp;&nbsp; node_buf->Global_ID_Num = Mesh.Nodes[local_id[0]].Global_ID_Num;</tt>
<br><tt>}</tt>
<p><tt>void user_unpack_node(void *data, int num_gid_entries,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> global_id, int size,&nbsp;</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;
char *buf, int *ierr)</tt>
<br><tt>{</tt>
<br><tt>/* <i>Copy the node data in buf into the Mesh data structure. </i>*/</tt>
<br><tt>int i;</tt>
<br><tt>struct Node_Type *node_buf = (struct Node_Type *) buf;</tt>
<p><tt>&nbsp;&nbsp;&nbsp; *ierr = ZOLTAN_OK;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; i = Mesh.Number_Owned;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; Mesh.Number_Owned = Mesh.Number_Owned + 1;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; Mesh.Nodes[i].Coordinates[0] = node_buf->Coordinates[0];</tt>
<br><tt>&nbsp;&nbsp;&nbsp; Mesh.Nodes[i].Coordinates[1] = node_buf->Coordinates[1];</tt>
<br><tt>&nbsp;&nbsp;&nbsp; Mesh.Nodes[i].Coordinates[2] = node_buf->Coordinates[2];</tt>
<br><tt>&nbsp;&nbsp;&nbsp; Mesh.Nodes[i].Global_ID_Num = node_buf->Global_ID_Num;</tt>
<br><tt>}</tt></td>
</tr>
<caption ALIGN=BOTTOM><i>Example of migration query functions for the <a href="#basic_query_example">Basic
Example</a>.</i></caption>
</table></center>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; |
<a href="ug_release.html">Next:&nbsp;
Release Notes</a>&nbsp; |&nbsp; <a href="ug_examples_mig.html">Previous:&nbsp;
Migration Examples</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

377
thirdParty/Zoltan/docs/ug_html/ug_fortran.html vendored Normal file
View File

@ -0,0 +1,377 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<TITLE>Zoltan User's Guide: FORTRAN Interface</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_interface.html">Next</a>&nbsp; |&nbsp; <a href="ug_cpp.html">Previous</a></i></b></div>
<H2>
<A NAME="fortran ug"></A>FORTRAN Interface</H2>
The Fortran interface for Zoltan is a Fortran 90 interface designed similar
to the Fortran 90 Bindings for OpenGL
[<A HREF="ug_refs.html#f90gl">Mitchell</A>]. There is no FORTRAN
77 interface; however, FORTRAN 77 applications can use Zoltan by adding
only a few Fortran 90 statements, which are fully explained in the section
on <A HREF="#fortran ug 77">FORTRAN 77</A>, provided that vendor-specific
extensions are not heavily used in the application. This section describes
how to build the Fortran interface into the Zoltan library, how to call
Zoltan from Fortran applications, and how to compile Fortran applications
that use Zoltan. Note that the capitalization used in this section is for
clarity and need not be adhered to in the application code, since Fortran
is case insensitive.
<UL><A HREF="#fortran ug compiling zoltan">Compiling Zoltan</A>
<BR><A HREF="#fortran ug compiling applications">Compiling Applications</A>
<BR><A HREF="#fortran ug api">FORTRAN API</A>
<BR><A HREF="#fortran ug 77">FORTRAN 77</A>
<BR><A HREF="#fortran ug sys">System Specific Remarks</A></UL>
<!---------------------------------------------------------------------------->
<HR>
<H2>
<A NAME="fortran ug compiling zoltan"></A>FORTRAN: Compiling Zoltan</H2>
Including the Fortran interface in the Zoltan library requires an additional
option on the <a href="ug_usage.html#Autotools">autotools configure</a> or
<a href="ug_usage.html#CMake">CMake</a> command:
<blockquote>
Autotools option: --enable-f90interface<br>
CMake option: -D Zoltan_ENABLE_F90INTERFACE:BOOL=ON<br>
</blockquote>
Before compiling the library, make sure that the application's
<a href="#fortran ug api query"><I>zoltan_user_data.f90</I></a>
has been placed in the <I>zoltan/src/fort/</I> directory, if needed.
<!---------------------------------------------------------------------------->
<hr>
<H2>
<A NAME="fortran ug compiling applications"></A>FORTRAN: Compiling Applications</H2>
To compile a Fortran application using the Zoltan library, the module
information
files must be made available to most compilers during the compilation phase.
Module information files are files generated by the compiler to provide
module information to program units that <B>USE </B>the module. They usually
have suffixes like .<I>mod</I> or <I>.M</I>. The module information files
for the modules in the Zoltan library are located in the <i>include</i>
directory generated during
<a href="ug_usage.html#Building the Library">Zoltan installation</a>.
Most Fortran 90 compilers have a compile line flag to specify directories
to be searched for module information files, typically "-I"; check the
documentation for your compiler. If your compiler does not have such a
flag, you will have to copy the module information files to the directory
of the application (or use symbolic links).
<P>The Fortran interface is built into the same library file as the rest
of Zoltan, which is found during the compiler link phase with <I>-lzoltan</I>.
Thus an example compilation line would be
<UL>f90 -I&lt;path to the installation include directory&gt;</I></a>
application.f90 -lzoltan </UL>
<!---------------------------------------------------------------------------->
<hr>
<h2>
<a NAME="fortran ug api"></a>FORTRAN API</h2>
The Fortran interface for each <a href="ug_interface.html">Zoltan Interface
Function</a> and <a href="ug_query.html">Application-Registered Query Function</a>
is given along with the C interface. This section contains some general
information about the design and use of the Fortran interface.
<ul><a href="#fortran ug api names">Names</a>
<br><a href="#fortran ug api zoltan module">Zoltan module</a>
<br><a href="#fortran ug api numeric types">Numeric types</a>
<br><a href="#fortran ug api structures">Structures</a>
<br><a href="#fortran ug api IDs">Global and local IDs</a>
<br><a href="#fortran ug api query">Query function data</a></ul>
<h3>
<a NAME="fortran ug api names"></a>Names</h3>
All procedure, variable, defined constant and structure names are identical
to those in the C interface, except that in Fortran they are case insensitive
(either upper or lower case letters can be used).
<br>&nbsp;
<h3>
<a NAME="fortran ug api zoltan module"></a>Zoltan module</h3>
MODULE <i>zoltan</i> provides access to all entities in Zoltan that are of use
to the application, including kind type parameters, named constants, procedures,
and derived types. Any program unit (e.g., main program, module, external
subroutine) that needs access to an entity from Zoltan must contain the
statement
<ul>USE zoltan</ul>
near the beginning.
<h3>
<a NAME="fortran ug api numeric types"></a>Numeric types</h3>
The correspondence between Fortran and C numeric types is achieved through
the use of kind type parameters. In most cases, the default kind for a
Fortran type will match the corresponding C type, but this is not guaranteed.
To insure portability of the application code, it is highly recommended
that the following kind type parameters be used in the declaration of all
variables and constants that will be passed to a Zoltan procedure:
<br>&nbsp;
<center><table BORDER WIDTH="80%" NOSAVE >
<tr NOSAVE>
<td NOSAVE><b>C</b></td>
<td><b>Fortran</b></td>
</tr>
<tr>
<td>int</td>
<td>INTEGER(KIND=Zoltan_INT)</td>
</tr>
<tr>
<td>float</td>
<td>REAL(KIND=Zoltan_FLOAT)</td>
</tr>
<tr>
<td>double</td>
<td>REAL(KIND=Zoltan_DOUBLE)&nbsp;</td>
</tr>
</table></center>
<p>Note that "KIND=" is optional in declaration statements. The kind number
for constants can be attached to the constant, e.g., 1.0_Zoltan_DOUBLE.
<br>&nbsp;
<h3>
<a NAME="fortran ug api structures"></a>Structures</h3>
For any struct in the C interface to Zoltan, e.g. <b><a href="../dev_html/dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>,
there is a corresponding derived type in the Fortran interface. Variables
of this type are declared as demonstrated below:
<ul>TYPE(Zoltan_Struct) :: zz</ul>
In the Fortran interface, the internal components of the derived type are
PRIVATE and not accessible to the application. However, the application
simply passes these variables around, and never needs to access the internal
components.
<h3>
<a NAME="fortran ug api IDs"></a>Global and local IDs</h3>
While the C implementation uses arrays of unsigned integers to represent
<a href="ug_usage.html#Data Types for Object IDs">global and local IDs</a>,&nbsp;
the Fortran interface uses arrays of integers, as unsigned integers are
not available in Fortran.&nbsp; Thus, each ID is represented as an array
(possibly of size 1) of integers.&nbsp; Applications that use other data
types for their IDs can convert between their data types and Zoltan's in
the <a href="ug_query.html">application-registered query functions</a>.
<h3>
<a NAME="fortran ug api query"></a>Query function data</h3>
<b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b> allows
the application to pass a pointer to data that will subsequently be passed
to the query function being registered. From Fortran this is an optional
argument, or can be one of several types. In the simplest cases, an intrinsic
array containing the data will be sufficient. For these cases, data can
be an assumed size array of type INTEGER(Zoltan_INT), REAL(Zoltan_FLOAT) or REAL(Zoltan_DOUBLE).
When the argument is omitted in the call to the registration function, a
data argument will still be passed to the query function. This should be
declared as an assumed size array of type INTEGER(Zoltan_INT) and never used.
<p>For more complicated situations, the application may need to pass data
in a user-defined type. The strong type checking of Fortran does not allow
passing an arbitrary type without modifying the Fortran interface for each
desired type. So the Fortran interface provides a type to be used for this
purpose, <b>Zoltan_User_Data_1</b>. Since different types of data may need
to be passed to different query functions, four such types are provided,
using the numerals 1, 2, 3 and 4 as the last character in the name of the
type. These types are defined by the application in <i>zoltan_user_data.f90</i>.
If not needed, they must be defined, but can be almost empty as in
<i>fort/zoltan_user_data.f90</i>.
<p>The application may use these types in any appropriate way. If desired,
it can define these types to contain the application's data and use the
type throughout the application. But it is anticipated that in most cases,
the desired type already exists in the application, and the <b>Zoltan_User_Data_x</b>
types will be used as "wrapper types," containing one or more pointers
to the existing types. For example,
<ul>TYPE mesh
<ul>! an existing data type with whatever defines a mesh</ul>
END TYPE mesh
<p>TYPE Zoltan_User_Data_2
<ul>TYPE(mesh), POINTER :: ptr</ul>
END TYPE Zoltan_User_Data_2</ul>
The application would then set the pointer to the data before calling Zoltan_Set_Fn:
<ul>TYPE(mesh) :: meshdata
<br>TYPE(Zoltan_User_Data_2) :: query_data
<br>TYPE(Zoltan_Struct) :: zz
<br>INTEGER(Zoltan_INT), EXTERNAL :: num_obj_func ! not required for module
procedures
<p>query_data%ptr => meshdata
<br>ierr = Zoltan_Set_Fn(zz,ZOLTAN_NUM_OBJ_FN_TYPE,num_obj_func,query_data)</ul>
Note that the existing data type must be available when <b>Zoltan_User_Data_x</b>
is defined. Therefore it must be defined either in<i> zoltan_user_data.f90</i>
or in a module that is compiled before <i>zoltan_user_data.f90</i> and <b>USE</b>d
by MODULE<i> zoltan_user_data</i>. For an example that uses a wrapper type,
see <i>fdriver/zoltan_user_data.f90</i>.
<p>
<!---------------------------------------------------------------------------->
<hr>
<H2>
<A NAME="fortran ug 77"></A>FORTRAN 77</H2>
There is no FORTRAN 77 interface for Zoltan; however, an existing FORTRAN
77 application can be compiled by a Fortran 90 compiler provided it does
not use vendor specific extensions (unless the same extensions are supported
by the Fortran 90 compiler), and the application can use Zoltan's Fortran
90 interface with a minimal amount of Fortran 90 additions. This section
provides details of the Fortran 90 code that must be added.
<P>When building the Zoltan library, use the file
<I>fort/zoltan_user_data.f90</I> for <I>zoltan_user_data.f90</I>.
This assumes that DATA in a
call to <B><A HREF="ug_interface_init.html#Zoltan_Set_Fn">ZOLTAN_SET_FN</A></B>
is either omitted (you can omit arguments that are labeled OPTIONAL in
the Fortran API) or an array of type INTEGER, REAL or DOUBLE PRECISION
(REAL*4 and REAL*8 might be acceptable). If a more complicated set of data
is required (for example, two arrays), then it should be made available
to the query functions through COMMON blocks.
<P>To get access to the interface, each program unit (main program, subroutine
or function) that calls a Zoltan routine must begin with the statement
<UL>USE ZOLTAN</UL>
and this should be the first statement after the program, subroutine or
function statement (before the declarations).
<P>The pointer to the Zoltan structure returned by <B><A HREF="ug_interface_init.html#Zoltan_Create">ZOLTAN_CREATE</A></B>
should be declared as
<UL>TYPE(ZOLTAN_STRUCT), POINTER :: ZZ</UL>
(you can use a name other than ZZ if you wish).
<P>To create the structure, use a pointer assignment statement with the call
to <B><A HREF="ug_interface_init.html#Zoltan_Create">ZOLTAN_CREATE</A></B>:
<UL>ZZ => <B><A HREF="ug_interface_init.html#Zoltan_Create">ZOLTAN_CREATE</A></B>(COMMUNICATOR)</UL>
Note that the assignment operator is "=>".
If ZZ is used in more than one procedure, then put it in a COMMON block.
It cannot be passed as an argument unless the procedure interfaces are
made "explicit." (Let's not go there.)
<P>The eight import and export arrays passed to <B><A HREF="ug_interface_lb.html#Zoltan_LB_Partition">ZOLTAN_LB_PARTITION</A></B>
(and other procedures) must be pointers. They should be declared as, for
example,
<UL>INTEGER, POINTER :: IMPORT_GLOBAL_IDS(:)</UL>
Note that the double colon after POINTER is required, and the dimension
must be declared as "(:)" with a colon.
Like ZZ, if they are used in more than one procedure, pass them through
a COMMON block, not as an argument.
<P>Except in the unlikely event that the default kinds of intrinsic types
do not match the C intrinsic types, you do not have to use the kind type
parameters <B>Zoltan_INT</B>, etc. It is also not necessary to include the
INTENT attribute in the declarations of the query functions, so they can
be simplified to, for example,
<UL>SUBROUTINE GET_OBJ_LIST(DATA, GLOBAL_IDS, LOCAL_IDS, WGT_DIM, OBJ_WGTS,
IERR)
<BR>INTEGER DATA(*),GLOBAL_IDS(*),LOCAL_IDS(*),WGT_DIM,IERR
<BR>REAL OBJ_WGTS(*)</UL>
to be more consistent with a FORTRAN 77 style.
<!---------------------------------------------------------------------------->
<hr>
<H2>
<A NAME="fortran ug sys"></A>FORTRAN: System-Specific Remarks</H2>
System-specific details of the FORTRAN&nbsp;interface are included below.
<P>
<H4>The mention of specific products, trademarks, or brand names is for
purposes of identification only. Such mention is not to be interpreted
in any way as an endoresement or certification of such products or brands
by the National Institute of Standards and Technology or Sandia National
Laboratories. All trademarks
mentioned herein belong to their respective owners.</H4>
<UL><A HREF="#fortran ug sys mpich">MPICH</A>
<BR><A HREF="#fortran ug sys pacific">Pacific Sierra</A>
<BR><A HREF="#fortran ug sys NAS">NASoftware</A></UL>
<H3>
<A NAME="fortran ug sys mpich"></A>MPICH</H3>
As of version 1.1.2, the MPICH implementation of MPI is not completely
"Fortran 90 friendly." Only one problem was encountered during our tests:&nbsp;
the reliance on command line arguments. MPICH uses command line arguments
during the start-up process, even if the application does not. Command
line arguments are not standard in Fortran, so although most compilers
offer it as an extension, each compiler has its own method of handling
them. The problem arises when one Fortran compiler is specified during
the build of MPICH and another Fortran compiler is used for the application.
This should not be a problem on systems where there is only one Fortran
compiler, or where multiple Fortran compilers are compatible (for example,
FORTRAN 77 and Fortran 90 compilers from the same vendor). If your program
can get past the call to MPI_Init, then you do not have this problem.
<P>To solve this problem, build MPICH in such a way that it does not include
the routines for <I>iargc</I> and <I>getarg</I> (I have been able to do
this by using the -f95nag flag when configuring MPICH), and then provide
your own versions of them when you link the application. Some versions
of these routines are provided in <I>fdriver/farg_*</I>.
<H3>
<A NAME="fortran ug sys pacific"></A>Pacific Sierra</H3>
Pacific Sierra Research (PSR) Vastf90 is not currently supported due to
bugs in the compiler with no known workarounds. It is not known when or
if this compiler will be supported.
<H3>
<A NAME="fortran ug sys NAS"></A>NASoftware</H3>
N.A.Software FortranPlus is not currently supported due to problems with
the query functions. We anticipate that this problem can be overcome, and
support will be added soon.
<P>
<!---------------------------------------------------------------------------->
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_interface.html">Next:&nbsp; Zoltan Interface Functions</A>&nbsp;
|&nbsp; <A HREF="ug_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>

206
thirdParty/Zoltan/docs/ug_html/ug_graph_build.html vendored Normal file
View File

@ -0,0 +1,206 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Graph interface</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg_hier.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_parmetis.html">Previous</a></i></b></div>
<h2>
<a NAME="Graph-build"></a>Graph build options</h2>
<p>
This page summarizes options relative to graph build for graph partitioning with <a href="ug_alg_parmetis.html">ParMetis</a>, <a href="ug_alg_ptscotch.html">Scotch</a>, sparse matrix ordering with <a href="ug_order_parmetis.html">ParMetis</a>, <a href="ug_order_ptscotch.html">Scotch</a>, and graph <a href="ug_interface_color.html">coloring</a>.
</p>
<table WIDTH="100%" NOSAVE >
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp; <i>CHECK_GRAPH</i></td>
<td nosave="">Level of error checking for graph input: 0 = no
checking, 1
= on-processor checking, 2 = full checking. (CHECK_GRAPH==2 is very
slow
and should be used only during debugging).</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>GRAPH_SYMMETRIZE</i></td>
<td nosave="">How to symmetrize the graph:
NONE = graph is symmetric and no symmetrization is needed <br/>
TRANSPOSE = if M is adjacency matrix of the input graph, output will be the graph representation of M+M<sup>T</sup> <br/>
BIPARTITE = graph is symmetrized in a bipartite way : [[ 0 M ][M<sup>t</sup> 0]]
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>GRAPH_SYM_WEIGHT</i></td>
<td nosave="">How edge weights are handled during symmetrization:
ADD = weights of each arc are added <br/>
MAX = only the heaviest arc weight is kept <br/>
<!-- ERROR = fail if complementary arcs don't have the same weight. -->
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>GRAPH_BUILD_TYPE</i></td>
<td nosave="">Type of input, do allow some optimizations in the build process:<br/>
NORMAL = graph is generic, no optimization can be performed<br/>
FAST = graph global IDs are in the interval [0,n-1], with IDs [0,a] on process 0, IDs [a+1, b] on process 1, IDs [b+1, c] on process 2, etc. <br/>
FAST_NO_DUP = graph global IDs are in the interval [0,n-1] with IDs [0,a] on process 0, IDs [a+1, b] on process 1, IDs [b+1, c] on process 2, etc., and there are no duplicate edges and no need of symmetrization.<br/>
See <i>GRAPH_FAST_BUILD_BASE</i> below to allow IDs to that are one-based instead of zero-based.
</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; <i>GRAPH_FAST_BUILD_BASE</i></td>
<td nosave="">When using <i>GRAPH_BUILD_TYPE</i> is FAST or FAST_NO_DUP,
IDs specified are in the range [GRAPH_FAST_BUILD_BASE, n-1+GRAPH_FAST_BUILD_BASE].
This parameter has no effect when <i>GRAPH_BUILD_TYPE</i> is NORMAL.
</td>
</tr>
<!-- <tr nosave="" valign="top"> -->
<!-- <td>&nbsp;&nbsp;&nbsp; <i>GRAPH_BIPARTITE_TYPE</i></td> -->
<!-- <td nosave=""> In the case of a bipartite symmetrization, -->
<!-- NONE = graph is symmetric and no symmetrization is needed <br/> -->
<!-- TRANSPOSE = if M is adjacency matrix of the input graph, output will be the graph representation of M+M<sup>T</sup> <br/> -->
<!-- BIPARTITE = graph is symmetrized in a bipartite way : [[ 0 M ][M<sup>t</sup> 0]] -->
<!-- </td> -->
<!-- </tr> -->
<tr>
<td valign="top"><b>Default values:</b></td>
<td><br>
</td>
</tr>
<tr>
<td><br>
</td>
<td><i>CHECK_GRAPH</i> = 1</td>
</tr>
<tr>
<td><br>
</td>
<td><i>GRAPH_SYMMETRIZE </i>= NONE</td>
</tr>
<tr>
<td><br>
</td>
<td><i>GRAPH_SYM_WEIGHT </i>= ADD</td>
</tr>
<tr>
<td><br>
</td>
<td><i>GRAPH_BUILD_TYPE </i>= NORMAL</td>
</tr>
<tr>
<td><br>
</td>
<td><i>GRAPH_FAST_BUILD_BASE </i>= 0</td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td NOSAVE>
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_F
N</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_F
N</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a></b>
</td>
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_alg_hier.html">Next:&nbsp;
Hybrid Hierarchical Partitioning</a>&nbsp; |&nbsp; <a href="ug_alg_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>

127
thirdParty/Zoltan/docs/ug_html/ug_graph_vs_hg.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.76 [en] (X11; U; Linux 2.4.2-2smp i686) [Netscape]">
<meta name="sandia.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Graph vs. Hypergraph Partitioning</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |
<a href="ug_alg_parmetis.html"> Next</a>&nbsp; |
&nbsp;<a href="ug_alg_graph.html">Previous</a>&nbsp;
</i>
</b></div>
<h2>
<a name="Graph vs Hypergraph Partitioning">
</a>Graph vs Hypergraph Partitioning</h2>
Graph partitioning has proven quite useful in scientific computing.
<a href="ug_alg_hypergraph.html">Hypergraph partitioning</a>
is a more recent improvement
that uses a hypergraph model, which is
often a more accurate model than the graph model for scientific computing.
(Hypergraphs contain hyperedges which connect two <i>or more</i>
vertices.)
See <a href="ug_refs.html#catalyurek99">[Catalyurek & Aykanat]</a> and
<a href="ug_refs.html#hendrickson-kolda">[Hendrickson & Kolda]</a>
for further details.
You do not need to understand the underlying models
to use graph or hypergraph partitioning for load-balancing
in Zoltan. The basic trade-offs are:
<ul>
<li> Hypergraph partitioning usually produces partitions (assignments)
of higher quality than graph partitioning, which may reduce
communication time in parallel applications (up to 30-40%
reduction has been reported). However, hypergraph
partitioning takes longer time to compute. </li>
<li> The graph model is restricted to symmetric data dependencies.
If you have a non-symmetric problem, we recommend hypergraph
partitioning. </li>
</ul>
<h3>Migrating from ParMetis to PHG in Zoltan</h3>
If you already use Zoltan for graph partitioning (via ParMetis),
there are three ways to switch to the Zoltan-PHG hypergraph partitioner:
<ol>
<li>The quick and easy way: Just change the <a href="ug_alg.html#LB_METHOD">
LB_METHOD</a> to "Hypergraph".
Zoltan will then use the graph query functions (presumably
already implemented) to construct a hypergraph model, which
is similar to but not equivalent to the graph.
<li>The proper way: Change the LB_METHOD, but also implement and
register the <a href="ug_query_lb.html#ZOLTAN_HG_SIZE_CS_FN">
hypergraph query functions</a>
required by Zoltan. These may give a more accurate representation
of data dependencies (and communication requirements) for your
application.
<li>If you really want graph (not hypergraph) partitioning:
Just change the <a href="ug_alg.html#LB_METHOD">
LB_METHOD</a> to "Graph".
Zoltan will then use PHG as a graph partitioner, which is slower than
ParMetis but often produces better partitions (lower cuts).
</ol>
Technical note: A hypergraph is constructed from the graph as follows:
The vertices are the same in the hypergraph as in the graph. For each vertex
<i>v</i>, create a hyperedge that consists of all neighbors in the graph
and <i>v </i> itself.
<hr width="100%">[<a href="ug.html">Table of Contents</a>&nbsp; |
<a href="ug_alg_parmetis.html"> Next:&nbsp; ParMETIS</a>&nbsp; |
&nbsp; <a href="ug_alg_graph.html">Previous:&nbsp;
Graph Partitioning</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

139
thirdParty/Zoltan/docs/ug_html/ug_index.html vendored Normal file
View File

@ -0,0 +1,139 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Index</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_refs.html">Previous</a></i></b></div>
<h2>
<a NAME="Index"></a>Index of Interface and Query Functions</h2>
<br><a href="ug_query_lb.html#ZOLTAN_CHILD_LIST_FN">ZOLTAN_CHILD_LIST_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_CHILD_WEIGHT_FN">ZOLTAN_CHILD_WEIGHT_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_COARSE_OBJ_LIST_FN">ZOLTAN_COARSE_OBJ_LIST_FN</a>
<br><a href="ug_interface_color.html#Zoltan_Color">Zoltan_Color</a>
<br><a href="ug_interface_mig.html#Zoltan_Compute_Destinations">Zoltan_Compute_Destinations</a>
<br><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a>
<br><a href="ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</a>
<br><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_FIRST_COARSE_OBJ_FN">ZOLTAN_FIRST_COARSE_OBJ_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_FIRST_OBJ_FN">ZOLTAN_FIRST_OBJ_FN</a> (deprecated)
<br><a href="ug_query_lb.html#ZOLTAN_FIXED_OBJ_LIST_FN">ZOLTAN_FIXED_OBJ_LIST_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a>
<br><a href="ug_interface_mig.html#Zoltan_Help_Migrate">Zoltan_Help_Migrate</a>
<br><a HREF="ug_query_lb.html#ZOLTAN_HIER_NUM_LEVELS_FN">ZOLTAN_HIER_NUM_LEVELS_FN</A>
<br><a HREF="ug_query_lb.html#ZOLTAN_HIER_PART_FN">ZOLTAN_HIER_PART_FN</A>
<br><a HREF="ug_query_lb.html#ZOLTAN_HIER_METHOD_FN">ZOLTAN_HIER_METHOD_FN</A>
<br><a href="ug_query_lb.html#ZOLTAN_HG_SIZE_CS_FN">ZOLTAN_HG_SIZE_CS_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_HG_CS_FN">ZOLTAN_HG_CS_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_HG_SIZE_EDGE_WTS_FN">ZOLTAN_HG_SIZE_EDGE_WTS_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_HG_EDGE_WTS_FN">ZOLTAN_HG_EDGE_WTS_FN</a>
<br><a href="ug_interface_init.html#Zoltan_Initialize">Zoltan_Initialize</a>
<br><a href="ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a>
<br><a href="ug_interface_lb.html#Zoltan_LB_Balance">Zoltan_LB_Balance</a>
<br><a href="ug_interface_augment.html#Zoltan_LB_Box_Assign">Zoltan_LB_Box_Assign</a>
<br><a href="ug_interface_augment.html#Zoltan_LB_Box_PP_Assign">Zoltan_LB_Box_PP_Assign</a>
<br><a href="ug_interface_lb.html#Zoltan_LB_Eval">Zoltan_LB_Eval</a>
<br><a href="ug_interface_lb.html#Zoltan_LB_Free_Data">Zoltan_LB_Free_Data</a>
<br><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a>
<br><a href="ug_interface_augment.html#Zoltan_LB_Point_Assign">Zoltan_LB_Point_Assign</a>
<br><a href="ug_interface_augment.html#Zoltan_LB_Point_PP_Assign">Zoltan_LB_Point_PP_Assign</a>
<br><a href="ug_interface_lb.html#Zoltan_LB_Set_Part_Sizes">Zoltan_LB_Set_Part_Sizes</a>
<br><a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_FN">ZOLTAN_MID_MIGRATE_FN</a>
<br><a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN">ZOLTAN_MID_MIGRATE_PP_FN</a>
<br><a href="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a>
<br><a href="ug_query_lb.html#ZOLTAN_NEXT_COARSE_OBJ_FN">ZOLTAN_NEXT_COARSE_OBJ_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_NEXT_OBJ_FN">ZOLTAN_NEXT_OBJ_FN</a> (deprecated)
<br><a href="ug_query_lb.html#ZOLTAN_NUM_CHILD_FN">ZOLTAN_NUM_CHILD_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_NUM_COARSE_OBJ_FN">ZOLTAN_NUM_COARSE_OBJ_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_NUM_FIXED_OBJ_FN">ZOLTAN_NUM_FIXED_OBJ_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a>
<br><a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN</a>
<br><a href="ug_interface_order.html#Zoltan_Order">Zoltan_Order</a>
<br><a href="ug_interface_order.html#Zoltan_Order_Get_Num_Blocks">Zoltan_Order_Get_Num_Blocks</a>
<br><a href="ug_interface_order.html#Zoltan_Order_Get_Block_Bounds">Zoltan_Order_Get_Block_Bounds</a>
<br><a href="ug_interface_order.html#Zoltan_Order_Get_Block_Size">Zoltan_Order_Get_Block_Size</a>
<br><a href="ug_interface_order.html#Zoltan_Order_Get_Block_Parent">Zoltan_Order_Get_Block_Parent</a>
<br><a href="ug_interface_order.html#Zoltan_Order_Get_Num_Leaves">Zoltan_Order_Get_Num_Leaves</a>
<br><a href="ug_interface_order.html#Zoltan_Order_Get_Block_Leaves">Zoltan_Order_Get_Block_Leaves</a>
<br><a href="ug_interface_order.html#Zoltan_Order_Get_GID_Order">Zoltan_Order_Get_GID_Order</a>
<br><a href="ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_PART_FN">ZOLTAN_PART_FN</a>
<br><a href="ug_query_lb.html#ZOLTAN_PART_MULTI_FN">ZOLTAN_PART_MULTI_FN</a>
<br><a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_FN">ZOLTAN_POST_MIGRATE_FN</a>
<br><a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN">ZOLTAN_POST_MIGRATE_PP_FN</a>
<br><a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_FN">ZOLTAN_PRE_MIGRATE_FN</a>
<br><a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN">ZOLTAN_PRE_MIGRATE_PP_FN</a>
<br><a href="ug_alg_rcb.html#Zoltan_RCB_Box">Zoltan_RCB_Box</a>
<br><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>
<br><a href="ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</a>
<br><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
<br><a href="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN</a>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_refs.html">Previous:&nbsp;
References</a> |&nbsp; <a href="../Zoltan.html">Zoltan Home Page</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

198
thirdParty/Zoltan/docs/ug_html/ug_interface.html vendored Normal file
View File

@ -0,0 +1,198 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Interface</title>
</head>
<body bgcolor="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_interface_init.html">Next</a>&nbsp; |&nbsp; <a href="ug_fortran.html">Previous</a></i></b></div>
<h2>
<a NAME="Zoltan Interface Functions"></a>Zoltan Interface Functions</h2>
An application calls a series of dynamic load-balancing library functions
to initialize the load balancer, perform load balancing and migrate data.
This section describes the syntax of each type of interface function:
<blockquote><a href="ug_interface_init.html">General Zoltan Interface Functions</a>
<br><a href="ug_interface_lb.html">Load-Balancing Interface Functions</a>
<br><a href="ug_interface_augment.html">Functions for Augmenting a Decomposition</a>
<br><a href="ug_interface_mig.html">Migration Interface Functions</a>
<br><a href="ug_interface_color.html">Graph Coloring Functions</a>
<br><a href="ug_interface_order.html">Graph Ordering Functions</a>
</blockquote>
Examples of the calling sequences for initialization, load-balancing, and
data migration are included in the <a href="ug_examples_init.html#Initialization Example">Initialization</a>,
<a href="ug_examples_lb.html#Load-Balancing Example">Load-Balancing</a>,
and <a href="ug_examples_mig.html#Migration Example">Migration</a> sections,
respectively, of the <a href="ug_examples.html#Examples of Library Usage">Examples
of Library Usage</a>.
<h2>
<a NAME="Error Codes"></a><hr>Error Codes</h2>
All interface functions, with the exception of <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
return an error code to the application. The possible return codes are
defined in <i>include/zoltan_types.h</i> and Fortran
<a href="ug_fortran_api.html#fortran ug api zoltan module">module zoltan</a>,
and are listed in the
<a href="#error codes table">table</a>
below.
<p>Note:&nbsp; Robust error handling in parallel has not yet been achieved
in Zoltan.&nbsp; When a processor returns from Zoltan due to an error condition,
other processors do not necessarily return the same condition.&nbsp; In
fact, other processors may not know that the original processor has returned
from Zoltan, and may wait indefinitely in a communication routine (e.g.,
waiting for a message from the original processor that is not sent due
to the error condition).&nbsp; The parallel error-handling capabilities
of Zoltan will be improved in future releases.
<br>&nbsp;
<center><table BORDER WIDTH="90%" >
<tr>
<td VALIGN=TOP><i>ZOLTAN_OK</i></td>
<td ALIGN=LEFT>Function returned without warnings or errors.</td>
</tr>
<tr>
<td VALIGN=TOP><i>ZOLTAN_WARN&nbsp;</i></td>
<td>Function returned with warnings. The application will probably be able
to continue to run.</td>
</tr>
<tr>
<td VALIGN=TOP><i>ZOLTAN_FATAL&nbsp;</i></td>
<td>A fatal error occured within the Zoltan library.</td>
</tr>
<tr>
<td VALIGN=TOP><i>ZOLTAN_MEMERR</i></td>
<td>An error occurred while allocating memory. When this error occurs,
the library frees any allocated memory and returns control to the application.
If the application then wants to try to use another, less memory-intensive
algorithm, it can do so.</td>
</tr>
<caption ALIGN=BOTTOM><a NAME="error codes table"></a><i>Return codes defined
in include/zoltan_types.h.</i></caption>
</table></center>
<h2>
<a NAME="Naming conventions"></a><hr>Naming conventions</h2>
The C, Fortran and C++ interfaces follow consistent naming conventions, as
illustrated in the following table.
<br> &nbsp;
<p>
<center><table BORDER WIDTH="90%" >
<tr>
<th align=center></th>
<th align=center>C and Fortran</th>
<th align=center>C++</th>
</tr>
<tr>
<td align=left>Partitioning and migration functions<br>
example: perform partitioning<br>
example: assign a point to a part</td>
<td align=left><B>Zoltan_LB_</b><i>function</i>()<br>
<b>Zoltan_LB_Partition()</b><br>
<b>Zoltan_LB_Point_Assign()</b><br> </td>
<td align=left><B>Zoltan::</b><i>function()</i><br>
<b>Zoltan::LB_Partition()</b><br>
<b>Zoltan::LB_Point_Assign()</b><br> </td>
</tr>
<tr>
<td align=left>Unstructured communication<br>
example: perform communication</td>
<td align=left><B>Zoltan_Comm_</b><i>function</i><br>
<b>Zoltan_Comm_Do()</b></td>
<td align=left><B>Zoltan_Comm::</b><i>function</i><br>
<b>Zoltan_Comm::Do()</b></td>
</tr>
<tr>
<td align=left>Distributed data<br>
example: find objects in a remote process</td>
<td align=left><B>Zoltan_DD_</b><i>function</i><br>
<b>Zoltan_DD_Find()</b></td>
<td align=left><B>Zoltan_DD::</b><i>function</i><br>
<b>Zoltan_DD::Find()</b></td>
</tr>
<tr>
<td align=left>Timers<br>
example: print timing results</td>
<td align=left><B>Zoltan_Timer_</b><i>function</i><br>
<b>Zoltan_Timer_Print()</b></td>
<td align=left><B>Zoltan_Timer::</b><i>function</i><br>
<b>Zoltan_Timer::Print()</b></td>
</table></center>
<p>
In particular, the C++ <B>Zoltan</b> class represents a load
balancing instance and the methods that operate on it. The method
name is identical to the part of the C and Fortran function name that
indicates the function performed. A C++ <B>Zoltan_Comm</b> object
represents an instance of unstructured communication, a C++
<b>Zoltan_DD</b> object represents a distributed directory, and a
C++ <b>Zoltan_Timer</b> object is a timer. Their
method names are derived similarly.
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a> |&nbsp; <a href="ug_interface_init.html">Next:&nbsp;
Initialization Functions</a>&nbsp; |&nbsp; <a href="ug_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>

497
thirdParty/Zoltan/docs/ug_html/ug_interface_augment.html vendored Normal file
View File

@ -0,0 +1,497 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<TITLE>Zoltan User's Guide: Augmenting a Decomposition</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_interface_mig.html">Next</a>&nbsp; |&nbsp; <a href="ug_interface_lb.html">Previous</a></i></b></div>
<H2>
Functions for Augmenting a Decomposition</H2>
The following functions support the addition of new items to an existing
decomposition. Given a decomposition, they determine to which processor(s)
a new item should be assigned. Currently, they work in conjunction with
only the
<A HREF="ug_alg_rcb.html">RCB</A>,
<a href="ug_alg_rib.html">RIB</a>, and
<A HREF="ug_alg_hsfc.html">HSFC</A>
algorithms.
<BLOCKQUOTE>
<B><A HREF="#Zoltan_LB_Point_PP_Assign">Zoltan_LB_Point_PP_Assign</A></B>
<BR><B><A HREF="#Zoltan_LB_Box_PP_Assign">Zoltan_LB_Box_PP_Assign</A></B>
</BLOCKQUOTE>
For <a href="ug_backward.html">backward compatibility</a>
with previous versions of Zoltan, the following
functions are also maintained.
These functions are applicable only when the
number of parts to be generated is equal to the number of processors on
which the parts are computed. That is, these functions assume "parts"
and "processors" are synonymous.
<blockquote>
<B><A HREF="#Zoltan_LB_Point_Assign">Zoltan_LB_Point_Assign</A></B>
<BR><B><A HREF="#Zoltan_LB_Box_Assign">Zoltan_LB_Box_Assign</A></B>
</blockquote>
<!------------------------------------------------------------------------->
<HR WIDTH="100%">
<A NAME="Zoltan_LB_Point_PP_Assign"></A>
<HR WIDTH="100%">
<TABLE WIDTH="100%" NOSAVE >
<TR NOSAVE>
<TD VALIGN=TOP NOSAVE>C:</TD>
<TD WIDTH="85%">
int <B>Zoltan_LB_Point_PP_Assign</B> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <B>Zoltan_Struct</B>
* <I>zz</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double * <I>coords</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * <I>proc</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * <I>part</I>
);&nbsp;
</TD>
</TR>
<TR NOSAVE>
<TD VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</TD>
<TD> FUNCTION <B>Zoltan_LB_Point_PP_Assign</B>(<I>zz, coords, proc, part</I>)
<BR> INTEGER(Zoltan_INT) :: Zoltan_LB_Point_PP_Assign&nbsp;
<BR> TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<BR> REAL(Zoltan_DOUBLE), DIMENSION(*), INTENT(IN) :: coords&nbsp;
<BR> INTEGER(Zoltan_INT), INTENT(OUT) :: proc&nbsp;
<BR> INTEGER(Zoltan_INT), INTENT(OUT) :: part&nbsp;</TD>
</TR>
<TR NOSAVE>
<TD VALIGN=TOP NOSAVE>C++:</TD>
<TD WIDTH="85%">
int <B>Zoltan::LB_Point_PP_Assign</B> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double * const <I>coords</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int & <I>proc</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int & <I>part</I>
);&nbsp;
</TD>
</TR>
</TABLE>
<HR WIDTH="100%"><B>Zoltan_LB_Point_PP_Assign</B> is used to determine to
which processor and parts
a new point should be assigned. It is applicable only to geometrically
generated decompositions
(<A HREF="ug_alg_rcb.html">RCB</A>,
<a href="ug_alg_rib.html">RIB</a>, and
<A HREF="ug_alg_hsfc.html">HSFC</A>).
If the parameter <B>KEEP_CUTS</B>
is set to TRUE, then the sequence of cuts that define the
decomposition is saved. Given a new geometric point, the processor and
parts which
own it can be determined.
<BR>&nbsp;
<TABLE WIDTH="100%" >
<TR>
<TD VALIGN=TOP WIDTH="20%"><B>Arguments:</B></TD>
<td WIDTH="80%"></td>
</TR>
<TR>
<TD><I>&nbsp;&nbsp;&nbsp; zz</I></TD>
<TD>Pointer to the Zoltan structure created by <B><A HREF="ug_interface_init.html#Zoltan_Create">Zoltan_Create</A></B>.</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; coords</I></TD>
<TD>The <I>(x,y)</I> or <I>(x,y,z)</I> coordinates of the point being assigned.</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; proc</I></TD>
<TD>Upon return, the ID of the processor to which the point should belong.</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp;&nbsp; part</I></TD>
<TD>Upon return, the ID of the parts to which the point should belong.</TD>
</TR>
<TR>
<TD><B>Returned Value:</B></TD>
<TD></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</TD>
<TD><A HREF="ug_interface.html#Error Codes">Error code</A>.</TD>
</TR>
</TABLE>
<!------------------------------------------------------------------------->
<HR WIDTH="100%">
<A NAME="Zoltan_LB_Box_PP_Assign"></A>
<HR WIDTH="100%">
<TABLE WIDTH="100%" NOSAVE >
<TR NOSAVE>
<TD VALIGN=TOP NOSAVE>C:</TD>
<TD WIDTH="85%">
int <B>Zoltan_LB_Box_PP_Assign</B> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <B>Zoltan_Struct</B> *<I> zz</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>xmin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>ymin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>zmin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>xmax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>ymax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>zmax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<I>procs</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<I>numprocs</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<I>parts</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<I>numparts</I>);
</TD>
</TR>
<TR NOSAVE>
<TD VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</TD>
<TD> FUNCTION <B>Zoltan_LB_Box_PP_Assign</B>(<I>zz,
xmin, ymin, zmin, xmax, ymax,
zmax, procs, numprocs, parts, numparts</I>)&nbsp;
<BR> INTEGER(Zoltan_INT) :: Zoltan_LB_Box_PP_Assign&nbsp;
<BR> TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<BR> REAL(Zoltan_DOUBLE), INTENT(IN) :: xmin, ymin, zmin, xmax, ymax, zmax&nbsp;
<BR> INTEGER(Zoltan_INT), DIMENSION(*), INTENT(OUT) ::procs&nbsp;
<BR> INTEGER(Zoltan_INT), INTENT(OUT) :: numprocs&nbsp;
<BR> INTEGER(Zoltan_INT), DIMENSION(*), INTENT(OUT) ::parts&nbsp;
<BR> INTEGER(Zoltan_INT), INTENT(OUT) :: numparts&nbsp;
</TD>
</TR>
<TR NOSAVE>
<TD VALIGN=TOP NOSAVE>C++:</TD>
<TD WIDTH="85%">
int <B>Zoltan::LB_Box_PP_Assign</B> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const double & <I>xmin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const double & <I>ymin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const double & <I>zmin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const double & <I>xmax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const double & <I>ymax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const double & <I>zmax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <I>procs</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int & <I>numprocs</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <I>parts</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int & <I>numparts</I>);
</TD>
</TR>
</TABLE>
<HR WIDTH="100%">In many settings, it is useful to know which processors
and parts
might need to know about an extended geometric object. <B>Zoltan_LB_Box_PP_Assign</B>
addresses this problem. Given a geometric decomposition of space (currently
only
<A HREF="ug_alg_rcb.html">RCB</A>,
<a href="ug_alg_rib.html">RIB</a>, and
<a href="ug_alg_hsfc.html">HSFC</a> are
supported), and given an axis-aligned box around the geometric
object, <B>Zoltan_LB_Box_PP_Assign</B> determines which processors and
parts own geometry that
intersects the box. To use this routine, the parameter <B>KEEP_CUTS</B>
must be set to TRUE when the decomposition is generated. This parameter
will cause the sequence of geometric cuts to be saved, which
is necessary for <B>Zoltan_LB_Box_PP_Assign</B> to do its job.
<p>
Note that if the parameter <B>REDUCE_DIMENSIONS</B> was set to TRUE and
the geometry was determined to be degenerate when decomposition was
calculated, then the calculation was performed on transformed
coordinates. This means that <B>Zoltan_LB_Box_PP_Assign</B>
must transform the supplied bounding box accordingly.
The transformed vertices are bounded again,
and the parts intersections are calculated in the transformed
space on this new bounding box.
The impact of this is that <B>Zoltan_LB_Box_PP_Assign</B> may return
parts not actually intersecting the original bounding box, but
it will not omit any parts intersecting the original bounding
box.
<BR>&nbsp;
<P>&nbsp;
<TABLE WIDTH="100%" >
<TR>
<TD VALIGN=TOP WIDTH="20%"><B>Arguments:</B></TD>
<td WIDTH="80%"></td>
</TR>
<TR>
<TD><I>&nbsp;&nbsp;&nbsp; zz</I></TD>
<TD>Pointer to the Zoltan structure created by <B><A HREF="ug_interface_init.html#Zoltan_Create">Zoltan_Create</A></B>.</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp; xmin, ymin, zmin</I></TD>
<TD>The coordinates of the lower extent of the bounding box around the
object.&nbsp; If the geometry is two-dimensional, the <i>z</i> value
is ignored.&nbsp;</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp; xmax, ymax, zmax</I></TD>
<TD>The coordinates of the upper extent of the bounding box around the
object.&nbsp; If the geometry is two-dimensional, the <i>z</i> value
is ignored.&nbsp;</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp; procs</I></TD>
<TD>The list of processors intersecting the box are returned starting at
this address. Note that <i>it is the responsibility of the calling routine
to ensure that there is sufficient space for the return list.</i>&nbsp;</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp; numprocs</I></TD>
<TD>Upon return, this value contains the number of processors that intersect
the box (i.e. the number of entries placed in the <I>procs</I> list).&nbsp;</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp; parts</I></TD>
<TD>The list of parts intersecting the box are returned starting at
this address. Note that <i>it is the responsibility of the calling routine
to ensure that there is sufficient space for the return list.</i>&nbsp;</TD>
</TR>
<TR>
<TD VALIGN=TOP><I>&nbsp;&nbsp; numparts</I></TD>
<TD>Upon return, this value contains the number of parts that intersect
the box (i.e. the number of entries placed in the <I>parts</I> list).&nbsp;</TD>
</TR>
<TR>
<TD><B>Returned Value:</B></TD>
<TD></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</TD>
<TD><A HREF="ug_interface.html#Error Codes">Error code</A>.</TD>
</TR>
</TABLE>
<!------------------------------------------------------------------------->
<HR WIDTH="100%">
<A NAME="Zoltan_LB_Point_Assign"></A>
<HR WIDTH="100%">
<TABLE WIDTH="100%" NOSAVE >
<TR NOSAVE>
<TD VALIGN=TOP NOSAVE>C:</TD>
<TD WIDTH="85%">
int <B>Zoltan_LB_Point_Assign</B> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <B>Zoltan_Struct</B>
* <I>zz</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double * <I>coords</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * <I>proc</I>);&nbsp;
</TD>
</TR>
<TR NOSAVE>
<TD VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</TD>
<TD> FUNCTION <B>Zoltan_LB_Point_Assign</B>(<I>zz, coords, proc</I>)&nbsp;
<BR> INTEGER(Zoltan_INT) :: Zoltan_LB_Point_Assign&nbsp;
<BR> TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<BR> REAL(Zoltan_DOUBLE), DIMENSION(*), INTENT(IN) :: coords&nbsp;
<BR> INTEGER(Zoltan_INT), INTENT(OUT) :: proc&nbsp;</TD>
</TR>
</TABLE>
<HR WIDTH="100%"><B>Zoltan_LB_Point_Assign</B> is
is a wrapper around
<a href="#Zoltan_LB_Point_PP_Assign"><b>Zoltan_LB_Point_PP_Assign</b></a>
that excludes
the parts assignment results. <b>Zoltan_LB_Point_Assign</b> assumes the
number of parts is equal to the number of processors; thus, the
parts assignment is equivalent to the processor assignment.
<BR>&nbsp;
<TABLE WIDTH="100%" >
<TR>
<TD VALIGN=TOP WIDTH="20%"><B>Arguments:</B></TD>
<td WIDTH="80%"></td>
</TR>
<tr>
<td VALIGN=TOP></td>
<td>All arguments are analogous to those in
<a href="#Zoltan_LB_Point_PP_Assign"><b>Zoltan_LB_Point_PP_Assign</b></a>.
Parts-assignment argument <i>part</i>
is not included, as processor and parts
numbers are considered to be the same in <b>Zoltan_LB_Point_Assign</b>.
</td>
</tr>
<TR>
<TD><B>Returned Value:</B></TD>
<TD></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</TD>
<TD><A HREF="ug_interface.html#Error Codes">Error code</A>.</TD>
</TR>
</TABLE>
<!------------------------------------------------------------------------->
<HR WIDTH="100%">
<A NAME="Zoltan_LB_Box_Assign"></A>
<HR WIDTH="100%">
<TABLE WIDTH="100%" NOSAVE >
<TR NOSAVE>
<TD VALIGN=TOP NOSAVE>C:</TD>
<TD WIDTH="85%">
int <B>Zoltan_LB_Box_Assign</B> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <B>Zoltan_Struct</B> *<I> zz</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>xmin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>ymin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>zmin</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>xmax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>ymax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;double <I>zmax</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<I>procs</I>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<I>numprocs</I>);
</TD>
</TR>
<TR NOSAVE>
<TD VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</TD>
<TD> FUNCTION <B>Zoltan_LB_Box_Assign</B>(<I>zz, xmin, ymin, zmin, xmax, ymax,
zmax, procs, numprocs</I>)&nbsp;
<BR> INTEGER(Zoltan_INT) :: Zoltan_LB_Box_Assign&nbsp;
<BR> TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<BR> REAL(Zoltan_DOUBLE), INTENT(IN) :: xmin, ymin, zmin, xmax, ymax, zmax&nbsp;
<BR> INTEGER(Zoltan_INT), DIMENSION(*), INTENT(OUT) ::procs&nbsp;
<BR> INTEGER(Zoltan_INT), INTENT(OUT) :: numprocs&nbsp;</TD>
</TR>
</TABLE>
<HR WIDTH="100%">
<b>Zoltan_LB_Box_Assign</b> is a wrapper around
<a href="#Zoltan_LB_Box_PP_Assign"><b>Zoltan_LB_Box_PP_Assign</b></a>
that excludes
the parts assignment results. <b>Zoltan_LB_Box_Assign</b> assumes the
number of parts is equal to the number of processors; thus, the
parts assignment is equivalent to the processor assignment.
<P>&nbsp;
<TABLE WIDTH="100%" >
<TR>
<TD VALIGN=TOP WIDTH="20%"><B>Arguments:</B></TD>
<td WIDTH="80%"></td>
</TR>
<TR>
<TD></TD>
<td>All arguments are analogous to those in
<a href="#Zoltan_LB_Box_PP_Assign"><b>Zoltan_LB_Box_PP_Assign</b></a>.
Parts-assignment arguments <i>parts</i> and <i>numparts</i>
are not included, as processor and parts
numbers are considered to be the same in <b>Zoltan_LB_Box_Assign</b>.
</td>
</TR>
<TR>
<TD><B>Returned Value:</B></TD>
<TD></TD>
</TR>
<TR>
<TD VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</TD>
<TD><A HREF="ug_interface.html#Error Codes">Error code</A>.</TD>
</TR>
</TABLE>
<!------------------------------------------------------------------------->
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_interface_mig.html">Next:&nbsp; Migration Functions</A>&nbsp;
|&nbsp; <A HREF="ug_interface_lb.html">Previous:&nbsp; Load-Balancing Functions</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]&nbsp;
</BODY>
</HTML>

181
thirdParty/Zoltan/docs/ug_html/ug_interface_color.html vendored Normal file
View File

@ -0,0 +1,181 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Coloring Interface</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_query.html">Next</a>&nbsp; |&nbsp; <a href="ug_interface_order.html">Previous</a></i></b></div>
<h2>
<a NAME="Coloring Functions"></a>Coloring Functions</h2>
Zoltan provides limited capability for coloring a set of objects,
typically given as a graph. In graph coloring, each vertex is
assigned an integer label such that no two adjacent vertices have
the same label.
The following functions are the coloring interface functions in the Zoltan
library; their descriptions are included below.
<blockquote><b><a href="#Zoltan_Color">Zoltan_Color</a></b>
</blockquote>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Color"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Color</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_gid_entries</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_obj</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR </a></b><i>global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>color_exp</i>);
</td>
</tr>
<tr>
<td>FORTRAN:</td>
<td>Not yet available.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Color</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int &<i>num_gid_entries</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const int &<i>num_obj</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR </a></b><i>global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>color_exp</i>);
</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Color </b>invokes the coloring routine and
the assigned colors of each object are returned in the array
<i>color_exp</i>. <i>color_exp[i]</i>gives the color of
<i>global_ids[i] </i>in the computed coloring. The arrays
<i>global_ids </i>and <i>color_exp</i> should all be allocated by the
application before <b>Zoltan_Color</b> is called. <i>global_ids</i>
must contain the global ids of the elements for which the current
processor wants coloring informations.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
to be used in this invocation of the load-balancing routine.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;&nbsp; <i>num_gid_entries</i></td>
<td>Input: the number of array entries used to describe a single
global ID.&nbsp; This value is the maximum value over all processors of
the parameter <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp;&nbsp; <i>num_obj</i></td>
<td NOSAVE>Number of objects for which we want to know the color on
this processor. Objects may be non-local or duplicated.</td> </tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; global_ids</i></td>
<td>An array of global IDs of objects for which we want to know the
color on this processor. Size of this array must be
<i>num_obj</i>. <br>Objects may be non-local. Objects IDs may be
repeated on several processor.</td> </tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; color_exp</i></td>
<td>Upon return, an array of length <i>num_obj</i> containing the
colors of objects. That is, <i>color_exp[i]</i> gives the color of
<i>global_ids[i]</i> in the computed coloring. By default, colors are
positive integers starting at one.
Memory for this array must have been allocated before <b>Zoltan_Color</b> is
called.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_query.html">Next:&nbsp;
Application-Registered Query Functions</a>&nbsp; |&nbsp; <a href="ug_interface_order.html">Previous:&nbsp;
Ordering Functions</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

822
thirdParty/Zoltan/docs/ug_html/ug_interface_init.html vendored Normal file
View File

@ -0,0 +1,822 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: General Zoltan Interface</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_interface_lb.html">Next</a>&nbsp; |&nbsp; <a href="ug_interface.html">Previous</a></i></b></div>
<h2>
<a NAME="Initialization Functions"></a>General Interface Functions</h2>
Functions used to initialize and manipulate Zoltan's data structures are
described below:
<ul><b><a href="#Zoltan_Initialize">Zoltan_Initialize</a></b>
<br><b><a href="#Zoltan_Create">Zoltan_Create</a></b>
<br><b><a href="#Zoltan_Copy">Zoltan_Copy</a></b>
<br><b><a href="#Zoltan_Copy_To">Zoltan_Copy_To</a></b>
<br><b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
<br><b><a href="#Zoltan_Set_Param_Vec">Zoltan_Set_Param_Vec</a></b>
<br><b><a href="#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
<br><b><a href="#Zoltan_Set_Specific_Fn">Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</a></b>
<br><b><a href="#Zoltan_Destroy">Zoltan_Destroy</a></b></ul>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Initialize"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C and C++:</td>
<td WIDTH="85%">int <b>Zoltan_Initialize</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int <i>argc</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char **<i>argv</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; float *<i>ver</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Initialize</b>( <i>argc</i>, <i>argv</i>,
<i>ver</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Initialize&nbsp;
<br>INTEGER(Zoltan_INT), INTENT(IN), OPTIONAL :: argc&nbsp;
<br>CHARACTER(LEN=*), DIMENSION(*), INTENT(IN), OPTIONAL :: argv&nbsp;
<br>REAL(Zoltan_FLOAT), INTENT(OUT) :: ver&nbsp;</td>
</tr>
</table>
<hr WIDTH="100%">The <b>Zoltan_Initialize</b> function initializes MPI
for Zoltan. If the application uses MPI, this function should be called
after calling <b>MPI_Init</b>. If the application does not use MPI, this
function calls <b>MPI_Init</b> for use by Zoltan. This function is called
with the <i>argc</i> and <i>argv</i> command-line arguments from the main
program, which are used if <b>Zoltan_Initialize</b> calls <b>MPI_Init</b>.
From C,&nbsp; if <b>MPI_Init</b> has already been called, the <i>argc</i>
and <i>argv</i> arguments may have any value because their values will
be ignored.&nbsp; From Fortran, if one of <i>argc</i> or <i>argv</i> is
omitted, they must both be omitted. If they are omitted,
<i>ver</i> does
NOT have to be passed as a keyword argument.
<p><b>Zoltan_Initialize</b> returns the Zoltan version number so that
users can verify which version of the library their application is linked
to.
<p>C++ applications should call the C <B>Zoltan_Initialize</B> function
before using the C++ interface to the Zoltan library.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%">&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; argc</i></td>
<td>The number of command-line arguments to the application.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; argv</i></td>
<td>An array of strings containing the command-line arguments to the application.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; ver</i></td>
<td>Upon return, the version number of the library.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td VALIGN=TOP><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Create"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C:</td>
<td WIDTH="85%">struct <b>Zoltan_Struct</b> *<b>Zoltan_Create</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MPI_Comm <i>communicator</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Create</b>(<i>communicator</i>)&nbsp;
<br>TYPE(Zoltan_Struct), pointer :: Zoltan_Create&nbsp;
<br>INTEGER, INTENT(IN) :: communicator&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C++:</td>
<td WIDTH="85%"><b>Zoltan</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const MPI_Comm &<i>communicator</i> = MPI_COMM_WORLD);</td>
</tr>
</table>
<hr WIDTH="100%">The <b>Zoltan_Create</b> function allocates memory for
storage of information to be used by Zoltan and sets the default values
for the information. The pointer returned by this function is passed to
many subsequent functions. An application may allocate more than one <b>Zoltan_Struct</b>
data structure; for example, an application may use several <b>Zoltan_Struct</b>
structures if, say, it uses different decompositions with different load-balancing
techniques.
<p>
In the C++ interface to Zoltan, the <B>Zoltan</B> class represents
a Zoltan load balancing data structure and the functions that operate on it.
It is the constructor which allocates an instance of a <b>Zoltan</B> object. It has
no return value.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; communicator</i></td>
<td>The MPI communicator to be used for this Zoltan structure. Only those
processors included in the communicator participate in Zoltan functions.
If all processors are to participate, <i>communicator</i> should be <b>MPI_COMM_WORLD</b>
.</td>
</tr>
<tr>
<td><b>Returned Value:&nbsp;</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *</td>
<td>Pointer to memory for storage of Zoltan information. If an error occurs,
NULL will be returned in C, or the result will be a nullified pointer in
Fortran. Any error that occurs in this function is assumed to be fatal.</td>
</tr>
</table>
<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Copy"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C:</td>
<td WIDTH="85%">struct <b>Zoltan_Struct</b> *<b>Zoltan_Copy</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>Zoltan_Struct</b> *<i>from</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Copy</b>(<i>from</i>)&nbsp;
<br>TYPE(Zoltan_Struct), pointer :: Zoltan_Copy&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: from &nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C++:</td>
<td WIDTH="85%"><b>Zoltan</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const Zoltan &<i>zz</i>);</td>
</tr>
</table>
<hr WIDTH="100%">The <b>Zoltan_Copy</b> function creates a new
<b>Zoltan_Struct</b> and copies the state of the existing <b>Zoltan_Struct</b>,
which it has been passed, to the new structure. It returns the new
<b>Zoltan_Struct</b>.
<p>
There is no direct interface to <B>Zoltan_Copy</B> from C++. Rather, the
<B>Zoltan</B> copy constructor invokes the C library <B>Zoltan_Copy</B>
program.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; from</i></td>
<td>A pointer to the <b>Zoltan_Struct</b> that is to be copied.
</td>
</tr>
<tr>
<td><b>Returned Value:&nbsp;</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *</td>
<td>Pointer to a new <b>Zoltan_Struct</b>, which is now a copy of <I>from</I>.
</td>
</tr>
</table>
<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Copy_To"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Copy_To</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>Zoltan_Struct</b> *<i>to</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>Zoltan_Struct</b> *<i>from</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Copy_To</b>(<i>to</i>, <i>from</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Copy_To&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: to &nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: from &nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>C++:</td>
<td WIDTH="85%"><b>Zoltan</b> & operator= (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const Zoltan &<i>zz</i>);</td>
</tr>
</table>
<hr WIDTH="100%">The <b>Zoltan_Copy_To</b> function copies one
<b>Zoltan_Struct</b> to another, after first freeing any memory used by the
target <b>Zoltan_Struct</b> and re-initializing it.
<p>
The C++ interface to the <B>Zoltan_Copy_To</B> function is through the
<B>Zoltan</B> copy operator, which invokes the C library <B>Zoltan_Copy_To</B>
program.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; to</i></td>
<td>A pointer to an existing <b>Zoltan_Struct</b>, the target of the copy.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; from</i></td>
<td>A pointer to an existing <b>Zoltan_Struct</b>, the source of the copy.
</td>
</tr>
<tr>
<td><b>Returned Value:&nbsp;</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><b>0</b> on success and <b>1</b> on failure.
</td>
</tr>
</table>
<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Set_Param"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Set_Param</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char *<i>param_name</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char *<i>new_val</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Set_Param</b>(<i>zz, param_name, new_val</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_Param&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<br>CHARACTER(LEN=*), INTENT(IN) :: param_name, new_value&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Set_Param</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &<b>param_name</b>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &<b>new_value</b>);</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Set_Param</b> is used to alter the value of
one of the parameters used by Zoltan.&nbsp; All Zoltan parameters have
reasonable default values, but this routine allows a user to provide alternative
values if desired.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td><i>&nbsp;&nbsp;&nbsp; zz</i></td>
<td>Pointer to the Zoltan structure created by <b><a href="#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; param_name</i></td>
<td>A string containing the name of the parameter to be altered.&nbsp;
Note that the string is case-insensitive.&nbsp; Also, different Zoltan
structures can have different parameter values.&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; new_val</i></td>
<td>A string containing the new value for the parameter.&nbsp; Example
strings include "3.154", "True", "7" or anything appropriate for the parameter
being set. As above, the string is case-insensitive.&nbsp;</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
<tr>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Set_Param_Vec"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Set_Param_Vec</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char *<i>param_name</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char *<i>new_val</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int <i>index</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Set_Param_Vec</b>(<i>zz, param_name, new_val, index</i>)
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_Param_Vec
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz
<br>CHARACTER(LEN=*), INTENT(IN) :: param_name, new_value
<br>INTEGER(Zoltan_INT), INTENT(IN) :: index</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Set_Param_Vec</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &<i>param_name</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &<i>new_val</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const int &<i>index</i>);</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Set_Param_Vec</b> is used to alter the value
of a vector parameter in Zoltan. A vector parameter is a parameter that
has one name but contains multiple values. These values are referenced
by their 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. If one only sets the values of a subset
of the indices for a vector parameter, the remaining entries will have
the default value for that particular parameter.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td><i>&nbsp;&nbsp;&nbsp; zz</i></td>
<td>Pointer to the Zoltan structure created by <b><a href="#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; param_name</i></td>
<td>A string containing the name of the parameter to be altered.&nbsp;
Note that the string is case-insensitive.&nbsp; Also, different Zoltan
structures can have different parameter values.&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; new_val</i></td>
<td>A string containing the new value for the parameter.&nbsp; Example
strings include "3.154", "True", "7" or anything appropriate for the parameter
being set. As above, the string is case-insensitive.&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; index</i></td>
<td>The index of the entry of the vector parameter to be set. The default
in Zoltan is that the first entry in a vector has index 0 (C-style indexing).</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Set_Fn"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Set_Fn</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct *</b><i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>ZOLTAN_FN_TYPE </b><i>fn_type</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void (*<i>fn_ptr</i>)(),
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<i>data</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Set_Fn</b>(<i>zz, fn_type, fn_ptr, data</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_Fn&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<br>TYPE(ZOLTAN_FN_TYPE), INTENT(IN) :: fn_type&nbsp;
<br>EXTERNAL :: fn_ptr&nbsp;
<br>&lt;<i>type-data</i>>, OPTIONAL :: data&nbsp;
<p>&lt;<i>type-data</i>> can be any of INTEGER(Zoltan_INT), DIMENSION(*)
or REAL(Zoltan_FLOAT), DIMENSION(*) or REAL(Zoltan_DOUBLE), DIMENSION(*)
or TYPE(Zoltan_User_Data_<i>x</i>) where <i>x</i> is 1, 2, 3 or 4. See
the section on
<a href="ug_fortran_api.html#fortran ug api query">Fortran
query functions</a> for an explanation.&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Set_Fn</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const <b>ZOLTAN_FN_TYPE </b> &<i>fn_type</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void (*<i>fn_ptr</i>)(),
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<i>data</i> = 0);</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Set_Fn</b> registers an application-supplied
query function in the Zoltan structure. All types of query functions can
be registered through calls to <b>Zoltan_Set_Fn</b>.&nbsp; To register
functions while maintaining strict type-checking of the <i>fn_ptr</i> argument,
use <b><a href="#Zoltan_Set_Specific_Fn">Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</a></b>.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<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 the Zoltan structure created by
<b><a href="#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; fn_type</i></td>
<td>The type of function being registered; see <a href="ug_query.html#Application-Registered Query Functions">Application-Registered
Query Functions</a> for possible function types.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; fn_ptr</i></td>
<td>A pointer to the application-supplied query function being registered.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; data</i></td>
<td>A pointer to user defined data that will be passed, as an argument,
to the function pointed to by <i>fn_ptr</i>. In C it may be NULL. In Fortran
it may be omitted.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Set_Specific_Fn"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct </b>*<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;<b><i><a href="ug_query.html">zoltan_fn_type</a></i></b>>
(*<i>fn_ptr</i>)(),&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<i>data</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>(<i>zz, fn_ptr,
data</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_&lt;<i><a href="ug_query.html">zoltan_fn_type</a></i>>_Fn&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<br>EXTERNAL :: fn_ptr&nbsp;
<br>&lt;<i>type-data</i>>, OPTIONAL :: data&nbsp;
<p>An interface block for <i>fn_ptr</i> is included in the FUNCTION definition
so that strict type-checking of the registered query function can be done.
<p>&lt;<i>type-data</i>> can be any of INTEGER(Zoltan_INT), DIMENSION(*)
or REAL(Zoltan_FLOAT), DIMENSION(*) or REAL(Zoltan_DOUBLE), DIMENSION(*)
or TYPE(Zoltan_User_Data_<i>x</i>) where <i>x</i> is 1, 2, 3 or 4. See
the section on
<a href="ug_fortran_api.html#fortran ug api query">Fortran
query functions</a> for an explanation.&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Set_&lt;<i>zoltan_fn_type</i>>_Fn</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;<b><i><a href="ug_query.html">zoltan_fn_type</a></i></b>>
(*<i>fn_ptr</i>)(),&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<i>data</i> = 0);</td>
</tr>
</table>
<hr WIDTH="100%">The interface functions <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>,
where <b>&lt;<i><a href="ug_query.html">zoltan_fn_type</a></i>></b> is
one of the query function types, register specific types of <a href="ug_query.html">application-supplied
query functions</a> in the Zoltan structure. One interface function exists
for each type of query function.&nbsp; For example, <b>Zoltan_Set_Num_Geom_Fn</b>
registers a query function of type <b><a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a></b>.&nbsp;
Each query function has an associated <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>.&nbsp;
A complete list of these functions is included in <i>include/zoltan.h.</i>
<p>Query functions can be registered using either <b><a href="#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>.
<br><b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn </b>provides strict type
checking of the <i>fn_ptr</i> argument; the argument's type is specified
for each
<b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>. <b><a href="#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
does not provide this strict type checking, as the pointer to the registered
function is cast to a void pointer.
<table WIDTH="100%" NOSAVE >
<tr>
<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 the Zoltan structure created by
<b><a href="#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; fn_ptr</i></td>
<td>A pointer to the application-supplied query function being registered.&nbsp;
The type of the pointer matches &lt;<b><i><a href="ug_query.html">zoltan_fn_type</a></i></b>>
in the name <b>Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</b>.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; data</i></td>
<td>A pointer to user defined data that will be passed, as an argument,
to the function pointed to by <i>fn_ptr</i>. In C it may be NULL. In Fortran
it may be omitted.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
<tr>
<td><b>Example:</b></td>
<td></td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE></td>
<td VALIGN=TOP NOSAVE>The interface function
<br>&nbsp;&nbsp;&nbsp; int <b>Zoltan_Set_Geom_Fn</b>(struct <b>Zoltan_Struct</b>
*zz, <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
(*fn_ptr)(),
<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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
void *data);
<br>registers an <b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
query function.</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Destroy"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">void <b>Zoltan_Destroy</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> **<i>zz</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>SUBROUTINE <b>Zoltan_Destroy</b>(<i>zz</i>)&nbsp;
<br>TYPE(Zoltan_Struct), POINTER :: zz&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">~<b>Zoltan</b> ();
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Destroy</b> frees the memory associated with
a Zoltan structure and sets the structure to NULL in C or nullifies the
structure in Fortran. Note that <b>Zoltan_Destroy</b> does not deallocate
the import and export arrays returned from Zoltan (e.g., the arrays returned
from <b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>);
these arrays can be deallocated through a separate call to <b><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
<p>
There is no explicit <B>Destroy</B> method in the C++ interface. The <B>Zoltan</B>
object is destroyed when the destructor executes.
<p>
As a side effect, <B>Zoltan_Destroy</B> (and the C++ <B>Zoltan</B>
destructor) frees the MPI communicator that
had been allocated for the structure. So it is important that the
application does not call <B>MPI_Finalize</B> before it calls
<B>Zoltan_Destroy</B> or before the destructor executes.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<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>A pointer to the address of the Zoltan structure, created by
<b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
to be destroyed.&nbsp;</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_interface_lb.html">Next:&nbsp;
Load-Balancing Functions</a>&nbsp; |&nbsp; <a href="ug_interface.html">Previous:&nbsp;
Zoltan Interface Functions</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

970
thirdParty/Zoltan/docs/ug_html/ug_interface_lb.html vendored Normal file
View File

@ -0,0 +1,970 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Load-Balancing Interface</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_interface_augment.html">Next</a>&nbsp; |&nbsp; <a href="ug_interface_init.html">Previous</a></i></b></div>
<h2>
<a NAME="Load-Balancing Functions"></a>Load-Balancing Functions</h2>
The following functions are the load-balancing interface functions in the
Zoltan library; their descriptions are included below.
<blockquote><b><a href="#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
<br><b><a href="#Zoltan_LB_Set_Part_Sizes">Zoltan_LB_Set_Part_Sizes</a></b>
<br><b><a href="#Zoltan_LB_Eval">Zoltan_LB_Eval</a></b>
<br><b><a href="#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b></blockquote>
For <a href="ug_backward.html">backward compatibility</a> with previous
versions of Zoltan, the following functions are also maintained. These
functions are applicable only when the number of parts to be generated
is equal to the number of processors on which the parts are computed.
That is, these functions assume "parts" and "processors" are synonymous.
<blockquote>
<b><a href="#Zoltan_LB_Balance">Zoltan_LB_Balance</a></b>
<br><b><a href="#Zoltan_LB_Free_Data">Zoltan_LB_Free_Data</a></b>
</blockquote>
Descriptions of algorithm-specific interface functions are included with
the documentation of their associated algorithms.
Algorithm-specific functions include:
<blockquote>
<b><a href="ug_alg_rcb.html#Zoltan_RCB_Box">Zoltan_RCB_Box</a></b>
</blockquote>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_LB_Partition"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_LB_Partition</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>changes</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>num_gid_entries</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>num_lid_entries</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>num_import</i>,&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>import_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>import_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>import_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>import_to_part</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>num_export</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>export_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>export_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>export_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>export_to_part</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_LB_Partition</b>(<i>zz, changes, num_gid_entries,
num_lid_entries, num_import, import_global_ids, import_local_ids, import_procs,
import_to_part, num_export, export_global_ids, export_local_ids, export_procs,
export_to_part</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_LB_Partition&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<br>LOGICAL, INTENT(OUT) :: changes&nbsp;
<br>INTEGER(Zoltan_INT), INTENT(OUT) :: num_gid_entries, num_lid_entries
<br>INTEGER(Zoltan_INT), INTENT(OUT) :: num_import, num_export&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_to_part, export_to_part</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::LB_Partition</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int &<i>changes</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int &<i>num_gid_entries</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int &<i>num_lid_entries</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int &<i>num_import</i>,&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
&<i>import_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
&<i>import_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int * &<i>import_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int * &<i>import_to_part</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int &<i>num_export</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
&<i>export_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
&<i>export_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int * &<i>export_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int * &<i>export_to_part</i>);</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_LB_Partition</b> invokes the load-balancing
routine specified by the <i><a href="ug_alg.html#LB_METHOD">LB_METHOD</a></i>
parameter. The number of parts it generates is specified by the <i><a href="ug_alg.html#NUM_GLOBAL_PARTS">NUM_GLOBAL_PARTS</a></i>
or
<i><a href="ug_alg.html#NUM_LOCAL_PARTS">NUM_LOCAL_PARTS</a></i>
parameters. Results of the partitioning are returned in lists of objects
to be imported into and exported from parts on this processor.
Objects are included in these lists if <i>either</i> their part
assignment or their processor assignment is changed by the new decomposition.
If an application requests multiple parts on a single processor, these
lists may include objects whose part assignment is changing, but whose
processor assignment is unchanged.
<p>
Returned arrays are allocated in Zoltan; applications
should not allocate these arrays before calling <b>Zoltan_LB_Partition</b>.
The arrays are later freed through calls to <b><a href="#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
to be used in this invocation of the load-balancing routine.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; changes</i></td>
<td>Set to 1 or .TRUE. if the decomposition was changed by the load-balancing
method; 0 or .FALSE. otherwise.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;&nbsp; <i>num_gid_entries</i></td>
<td>Upon return, the number of array entries used to describe a single
global ID.&nbsp; This value is the maximum value over all processors of
the parameter <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;&nbsp; <i>num_lid_entries</i></td>
<td>Upon return, the number of array entries used to describe a single
local ID.&nbsp; This value is the maximum value over all processors of
the parameter <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; num_import&nbsp;</i></td>
<td>Upon return, the number of objects
that are newly assigned to this processor or to parts on this processor
(i.e., the number of objects being imported from different parts to
parts on this processor).
If the value returned
is -1, no import information has been returned and all import arrays below
are NULL. (The
<a href="ug_alg.html#RETURN_LISTS">RETURN_LISTS</a> parameter
determines whether import lists are returned).</td>
</tr>
<tr>
<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 parts on this processor.
<br>(size = <i>num_import</i> * <i>num_gid_entries</i>)</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_local_ids</i></td>
<td>Upon return, an array of&nbsp; <i>num_import</i> local IDs of objects
to be imported to parts on this processor.
<br>(size = <i>num_import</i> * <i>num_lid_entries</i>)</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_procs</i></td>
<td>Upon return, an array of size <i>num_import</i> listing the processor
IDs of the processors that owned the imported objects in the previous decomposition
(i.e., the source processors).</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_to_part</i></td>
<td>Upon return, an array of size <i>num_import</i> listing the parts
to which the imported objects are being imported.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; num_export</i></td>
<td>Upon return, this value of this count and the following lists
depends on the value of
the <a href="ug_alg.html#RETURN_LISTS">RETURN_LISTS</a> parameter:
<UL>
<LI>It is the count of objects on this processor
that are newly assigned to other processors or to other parts
on this processor, if
<a href="ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>
is "EXPORT" or "EXPORT AND IMPORT".
<LI>It is the count of all objects on this processor,
if
<a href="ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>
is "PARTS" (or "PART ASSIGNMENTS").
<LI>It is -1 if the value of
<a href="ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>
indicates that either no lists are to be returned, or only import lists
are to be returned.
If the value returned
is -1, no export information has been returned and all export arrays below
are NULL .
</UL>
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_global_ids</i></td>
<td>Upon return, an array of <i>num_export</i> global IDs of objects to
be exported from parts on this processor
(if <a href="ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>
is equal to "EXPORT" or "EXPORT AND IMPORT"),
or an array of <i>num_export</i> global IDs
for every object on this processor
(if <a href="ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>
is equal to "PARTS" or "PART ASSIGNMENTS"),
.&nbsp;
<br>(size = <i>num_export</i> * <i>num_gid_entries</i>)</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_local_ids</i></td>
<td>Upon return, an array of <i>num_export</i> local IDs associated
with the global IDs returned in <i>export_global_ids</i>
<br>(size = <i>num_export</i> * <i>num_lid_entries</i>)</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_procs</i></td>
<td>Upon return, an array of size <i>num_export </i>listing the processor
ID of the processor to which each object is now assigned
(i.e., the destination processor).
If <a href="ug_alg.html#RETURN_LISTS">RETURN_LISTS</a>
is equal to "PARTS" or "PART ASSIGNMENTS", this list includes all objects, otherwise
it only includes the objects which are moving to a new part and/or process.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_to_part</i></td>
<td>Upon return, an array of size <i>num_export</i> listing the parts
to which the objects are assigned under the new partition.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_LB_Set_Part_Sizes"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_LB_Set_Part_Sizes</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int <i>global_num,</i>
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int <i>len</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>part_ids,</i>
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>wgt_idx</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; float *<i>part_sizes</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td WIDTH="85%">
function <b>Zoltan_LB_Set_Part_Sizes</b>(
<i>zz,global_part,len,partids,wgtidx,partsizes</i>)
<br>integer(Zoltan_INT) :: Zoltan_LB_Set_Part_Sizes
<br>type(Zoltan_Struct) INTENT(IN) zz
<br>integer(Zoltan_INT) INTENT(IN) global_part,len,partids(*),wgtidx(*)
<br>real(Zoltan_FLOAT) INTENT(IN) partsizes(*)
</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::LB_Set_Part_Sizes</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const int &<i>global_num,</i>
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const int &<i>len</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>part_ids,</i>
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>wgt_idx</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; float *<i>part_sizes</i>);</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_LB_Set_Part_Sizes</b> is used to specify the
desired part sizes in Zoltan. By default, Zoltan assumes that all
parts should be of equal size.&nbsp; With <b>Zoltan_LB_Set_Part_Sizes</b>,
one can specify the relative (not absolute) sizes of the parts. For
example, if two parts are requested and the desired sizes are 1 and
2, that means that the first part will be assigned approximately one
third of the total load. If the sizes were instead given as 1/3 and 2/3,
respectively, the result would be exactly the same. Note that if there
are multiple weights per object, one can (must) specify the part size
for each weight dimension independently.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td><i>&nbsp;&nbsp;&nbsp; zz</i></td>
<td>Pointer to the Zoltan structure created by <b><a href="#Zoltan_Create">Zoltan_Create</a></b>.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; global_num</i></td>
<td>Set to 1 if global part numbers are given, 0 otherwise (local
part numbers).</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp; len</i></td>
<td>Length of the next three input arrays.</td>
</tr>
<tr>
<td>&nbsp;&nbsp; <i>part_ids</i></td>
<td>Array of part numbers, either global or local. (Part numbers
are integers starting from 0.)</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp; <i>vwgt_idx</i></td>
<td NOSAVE>Array of weight indices (between 0 and OBJ_WEIGHT_DIM-1). This
array should contain all zeros when there is only one weight per object.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp; <i>part_sizes</i></td>
<td NOSAVE>Relative values for part sizes; <i>part_sizes[i]</i> is
the desired relative size of the <i>vwgt_idx[i]</i>'th weight of part
<i>part_ids[i].</i></td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
<tr>
<td></td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_LB_Eval"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_LB_Eval</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int <i>print_stats</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ZOLTAN_BALANCE_EVAL *<i>obj_info</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ZOLTAN_GRAPH_EVAL *<i>graph_info</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ZOLTAN_HG_EVAL *<i>hg_info</i>);&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_LB_Eval</b>(<i>zz, print_stats</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_LB_Eval
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<br>LOGICAL, INTENT(IN) :: print_stats&nbsp;
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::LB_Eval</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const int &<i>print_stats</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ZOLTAN_BALANCE_EVAL *<i>obj_info</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ZOLTAN_GRAPH_EVAL *<i>graph_info</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ZOLTAN_HG_EVAL *<i>hg_info</i>);&nbsp;</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_LB_Eval </b>evaluates the quality of a decomposition.
The quality metrics of interest differ depending on how you are using Zoltan.
If you are partitioning points in space using one of Zoltan's geometric methods,
you will want to know the weighted balance of objects across parts. However
if you are partitioning a graph, you will want to know about edges that have
vertices in more than one part. <b>Zoltan_LB_Eval </b> can write three
different structures with these differing metrics.
<p>
<table WIDTH="100%" NOSAVE >
<tr>
<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 the Zoltan structure.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; print_stats</i></td>
<td>If <i>print_stats</i>>0 (.TRUE. in Fortran), print the quality metrics to <i>stdout.</i></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; obj_info</i></td>
<td>If <i>obj_info</i>is non-NULL, write object balance values to the <a href="#ZOLTAN_BALANCE_EVAL">ZOLTAN_BALANCE_EVAL</a> structure.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; graph_info</i></td>
<td>If <i>graph_info</i>is non-NULL, write graph partition metrics to the <a href="#ZOLTAN_GRAPH_EVAL">ZOLTAN_GRAPH_EVAL</a> structure.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; hg_info</i></td>
<td>If <i>hg_info</i>is non-NULL, write hypergraph partition metrics to the <a href="#ZOLTAN_HG_EVAL">ZOLTAN_HG_EVAL</a> structure.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code.</a></td>
</tr>
</table>
<p>
The EVAL structures are defined in <i>zoltan/src/include/zoltan_eval.h</i>.
Several of the fields in the EVAL structures are arrays of values.
The arrays contain values for
<ol>
<li>the total for the local process
<li>the total across all parts
<li>the minimum across all parts
<li>the maximum across all parts
<li>the average across all parts
</ol>
<p>
in that order. The corresponding macros that refer to these fields are:
<p>
<code>
#define EVAL_LOCAL_SUM 0<br>
#define EVAL_GLOBAL_SUM 1<br>
#define EVAL_GLOBAL_MIN 2<br>
#define EVAL_GLOBAL_MAX 3<br>
#define EVAL_GLOBAL_AVG 4<br>
</code>
<p>
<a NAME="ZOLTAN_BALANCE_EVAL"></a>
The ZOLTAN_BALANCE_EVAL structure contains the following fields, and
would be of interest if you are doing geometric partitioning:
<p>
<UL>
<li><strong>obj_imbalance</strong>: imbalance in count of objects across parts, scaled by
requested part sizes.
<li><strong>imbalance</strong>: imbalance in weight of objects across parts, scaled by
requested part sizes.
<li><strong>nobj</strong>: an array containing the number of objects on the local <em>process</em>, the total number of objects, the minimum number of objects in a <em>part</em>, the maximum number in a partitition, and the average number of objects across the parts.
<li><strong>obj_wgt</strong>: an array containing the sum of the weight of objects on the local <em>process</em>, the total weight across all processes, the minimum weight in a <em>part</em>, the maximum weight in a partitition, and the average weight of objects across the parts.
<li><strong>xtra_imbalance</strong>: if the <a href="ug_param.html#OBJ_WEIGHT_DIM">OBJ_WEIGHT_DIM</a> exceeds one, the <strong>obj_imbalance</strong> value for the extra weights is in this array.
<li><strong>xtra_obj_wgt</strong>: if the <a href="ug_param.html#OBJ_WEIGHT_DIM">OBJ_WEIGHT_DIM</a> exceeds one, the <strong>obj_wgt</strong> array for the extra weights is in this array.
</UL>
<p>
<a NAME="ZOLTAN_GRAPH_EVAL"></a>
The ZOLTAN_GRAPH_EVAL structure contains the following fields, and
would be of interest if you are doing graph partitioning:
<p>
<UL>
<li><strong>cutl</strong>: an array containing what is known at the CUTL or the ConCut measure of the graph, the first element is not set (this is the local process total, which has no meaning), the next is the sum of the CUTL across parts, then the minimum CUTL across parts, then the maximum CUTL across parts, finally the average CUTL across parts.
<li><strong>cutn</strong>: an array containing what is known at the CUTN or the NetCut measure of the graph, the first element is not set, the next is the sum of the CUTL across parts, then the minimum CUTL across parts, then the maximum CUTL across parts, finally the average CUTL across parts.
<li><strong>cuts</strong>: an array counting the number of cut edges (the first element again is not set) across all parts, the minimum across parts of cut edges, the maximum, and then the average
<li><strong>cut_weight</strong>: an array summing the weight of cut edges (the first element again is not set) across all parts, the minimum across parts, the maximum, and then the average
<li><strong>nnborparts</strong>: an array which counts the number of neighboring parts that each part has, the first element again is not set, the next is the sum across all parts, the minimum across parts, the maximum, and then the average
<li><strong>obj_imbalance</strong>: imbalance in count of objects across parts, scaled by
requested part sizes.
<li><strong>imbalance</strong>: imbalance in weight of objects across parts, scaled by
requested part sizes.
<li><strong>nobj</strong>: an array containing the number of objects on the local <em>process</em>, the total number of objects, the minimum number of objects in a <em>part</em>, the maximum number in a partitition, and the average number of objects across the parts.
<li><strong>obj_wgt</strong>: an array containing the sum of the weight of objects on the local <em>process</em>, the total weight across all processes, the minimum weight in a <em>part</em>, the maximum weight in a partitition, and the average weight of objects across the parts.
<li><strong>num_boundary</strong>: an array which counts the number of objects in a part that have at least one remote neighbor, the first element is not set, the next is the sum across parts, the next is the minimum count in any part, the next is the maximum, and then the average for all parts
<li><strong>xtra_imbalance</strong>: if the <a href="ug_param.html#OBJ_WEIGHT_DIM">OBJ_WEIGHT_DIM</a> exceeds one, the <strong>obj_imbalance</strong> value for the extra weights is in this array.
<li><strong>xtra_obj_wgt</strong>: if the <a href="ug_param.html#OBJ_WEIGHT_DIM">OBJ_WEIGHT_DIM</a> exceeds one, the <strong>obj_wgt</strong> array for the extra weights is in this array.
<li><strong>xtra_cut_wgt</strong>: if the <a href="ug_param.html#EDGE_WEIGHT_DIM">EDGE_WEIGHT_DIM</a> exceeds one, the <strong>cut_wgt</strong> array for the each extra weight is in this array.
</UL>
<p>
<p>
<a NAME="ZOLTAN_HG_EVAL"></a>
The ZOLTAN_HG_EVAL structure contains the following fields, and
would be of interest if you are doing hypergraph partitioning:
<p>
<UL>
<li><strong>obj_imbalance</strong>: imbalance in count of objects across parts, scaled by
requested part sizes.
<li><strong>imbalance</strong>: imbalance in weight of objects across parts, scaled by
requested part sizes.
<li><strong>cutl</strong>: an array containing what is known at the CUTL or the ConCut measure of the hypergraph, the first element is not set (this is the local process total, which has no meaning), the next is the sum of the CUTL across parts, then the minimum CUTL across parts, then the maximum CUTL across parts, finally the average CUTL across parts.
<li><strong>cutn</strong>: an array containing what is known at the CUTN or the NetCut measure of the hypergraph, the first element is not set, the next is the sum of the CUTL across parts, then the minimum CUTL across parts, then the maximum CUTL across parts, finally the average CUTL across parts.
<li><strong>nobj</strong>: an array containing the number of objects on the local <em>process</em>, t
he total number of objects, the minimum number of objects in a <em>part</em>, the maximum number
in a partitition, and the average number of objects across the parts.
<li><strong>obj_wgt</strong>: an array containing the sum of the weight of objects on the local <em>p
rocess</em>, the total weight across all processes, the minimum weight in a <em>part</em>, the m
aximum weight in a part, and the average weight of objects across the parts.
<li><strong>xtra_imbalance</strong>: if the <a href="ug_param.html#OBJ_WEIGHT_DIM">OBJ_WEIGHT_DIM</a>
exceeds one, the <strong>obj_imbalance</strong> value for the extra weights is in this array.
<li><strong>xtra_obj_wgt</strong>: if the <a href="ug_param.html#OBJ_WEIGHT_DIM">OBJ_WEIGHT_DIM</a> e
xceeds one, the <strong>obj_wgt</strong> array for the extra weights is in this array.
</UL>
<p>
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP NOSAVE>
<td><b>Query functions:</b>
</td>
</tr>
<tr>
<td>
<br>&nbsp;&nbsp;&nbsp;&nbsp; Required:</td>
<td NOSAVE>
<br><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a>
and <a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a>
</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp;&nbsp;&nbsp; Optional:</td>
<td NOSAVE>
<a href="ug_query_lb.html#Graph-based Functions">Graph-Based</a> functions are required
for writing the <a href="#ZOLTAN_GRAPH_EVAL">ZOLTAN_GRAPH_EVAL</a> structure.
<br>
<a href="ug_query_lb.html#Hypergraph-based Functions">Hypergraph-Based</a> functions will be used
for writing the <a href="#ZOLTAN_HG_EVAL">ZOLTAN_HG_EVAL</a> if they are available,
otherwise Zoltan will create a hypergraph from the
<a href="ug_query_lb.html#Graph-based Functions">graph-Based</a> functions.
<br>
If <a href="ug_interface_lb.html#Zoltan_LB_Set_Part_Sizes">Zoltan_LB_Set_Part_Sizes</a> has been
called, the part sizes set by the <a href="ug_interface_lb.html#Zoltan_LB_Set_Part_Sizes">Zoltan_LB_Set_Part_Sizes</a>
will be used in calculating imbalances.
</td>
</tr>
</table>
<p>Note that the sum of <i>ncuts</i> over all processors is actually twice
the number of edges cut in the graph (because each edge is counted twice).
The same principle holds for <i>cut_wgt.</i><i></i>
<p>There are a few improvements in Zoltan_LB_Eval&nbsp; in Zoltan version
1.5 (or higher). First, the balance data are computed with respect to both
processors and parts (if applicable). Second, the desired part
sizes (as set by Zoltan_LB_Set_Part_Sizes)&nbsp; are taken into account
when computing the imbalance.
<p>Known bug: If a part is spread across several processors, the computed
cut information (<i>ncuts </i>and <i>cut_wgt)</i> may be incorrect (too
high).
<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_LB_Free_Part"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_LB_Free_Part</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>procs</i>,&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>to_part</i>);</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_LB_Free_Part</b>(<i>global_ids, local_ids, procs,
to_part</i>)
<br>INTEGER(Zoltan_INT) :: Zoltan_LB_Free_Part&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: global_ids
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: local_ids
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: procs, to_part</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::LB_Free_Part</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>procs</i>,&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>to_part</i>);</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_LB_Free_Part</b> frees the memory allocated
by Zoltan to return the results of <b><a href="#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
or
<b><a href="ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a></b>.
Memory pointed to by the arguments is freed and the arguments are set to
NULL in C and C++ or nullified in Fortran. NULL arguments may be passed to <b>Zoltan_LB_Free_Part</b>.
Typically, <b>Zoltan_LB_Free_Part</b> is called twice: once for the import lists, and once for the export lists.<br>
Note that this function does not destroy the Zoltan data structure itself;
it is deallocated through a call to <b><a href="ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</a></b>
in C and Fortran and by the object destructor in C++.
<br>
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; global_ids</i></td>
<td>An array containing the global IDs of objects.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; local_ids</i></td>
<td>An array containing the local IDs of objects.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; procs</i></td>
<td>An array containing processor IDs.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; to_part</i></td>
<td>An array containing part numbers.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.&nbsp;</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_LB_Balance"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_LB_Balance</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>changes</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>num_gid_entries</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>num_lid_entries</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>num_import</i>,&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>import_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>import_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>import_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int *<i>num_export</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>export_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>export_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>export_procs</i>);&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_LB_Balance</b>(<i>zz, changes, num_gid_entries,
num_lid_entries, num_import, import_global_ids, import_local_ids, import_procs,
num_export, export_global_ids, export_local_ids, export_procs</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_LB_Balance&nbsp;
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz&nbsp;
<br>LOGICAL, INTENT(OUT) :: changes&nbsp;
<br>INTEGER(Zoltan_INT), INTENT(OUT) :: num_gid_entries, num_lid_entries
<br>INTEGER(Zoltan_INT), INTENT(OUT) :: num_import, num_export&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs&nbsp;</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_LB_Balance</b> is a wrapper around
<b><a href="#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
that excludes the part assignment results. <b>Zoltan_LB_Balance</b>
assumes the number of parts is equal to the number of processors;
thus, the part assignment is equivalent to the processor assignment.
Results of the partitioning are returned in lists of objects to be imported
and exported. These arrays are allocated in Zoltan; applications should
not allocate these arrays before calling <b>Zoltan_LB_Balance</b>. The
arrays are later freed through calls to <b><a href="#Zoltan_LB_Free_Data">Zoltan_LB_Free_Data</a></b>
or
<b><a href="#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>All arguments are analogous to those in <b><a href="#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>.
Part-assignment arguments <i>import_to_part</i> and <i>export_to_part</i>
are not included, as processor and parts numbers are considered to
be the same in <b>Zoltan_LB_Balance</b>.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<p><!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_LB_Free_Data"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_LB_Free_Data</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>import_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>import_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>import_procs</i>,&nbsp;
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>export_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a></b>
*<i>export_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int **<i>export_procs</i>);&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_LB_Free_Data</b>(<i>import_global_ids, import_local_ids,
import_procs, export_global_ids, export_local_ids, export_procs</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_LB_Free_Data&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs&nbsp;</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_LB_Free_Data</b> frees the memory allocated
by the Zoltan to return the results of <b><a href="#Zoltan_LB_Balance">Zoltan_LB_Balance</a></b>
or
<b><a href="ug_interface_mig.html#Zoltan_Compute_Destinations">Zoltan_Compute_Destinations</a></b>.
Memory pointed to by the arguments is freed and the arguments are set to
NULL in C or nullified in Fortran. NULL arguments may be passed to <b>Zoltan_LB_Free_Data</b>.
Note that this function does not destroy the Zoltan data structure itself;
it is deallocated through a call to <b><a href="ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</a></b>.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_global_ids</i></td>
<td>The array containing the global IDs of objects imported to this processor.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_local_ids</i></td>
<td>The array containing the local IDs of objects imported to this processor.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_procs</i></td>
<td>The array containing the processor IDs of the processors that owned
the imported objects in the previous decomposition (i.e., the source processors).</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_global_ids&nbsp;</i></td>
<td>The array containing the global IDs of objects exported from this processor.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_local_ids</i></td>
<td>The array containing the local IDs of objects exported from this processor.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_procs</i></td>
<td>The array containing the processor IDs of processors that own the exported
objects in the new decomposition (i.e., the destination processors).</td>
</tr>
<tr>
<td VALIGN=TOP><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.&nbsp;</td>
</tr>
</table>
<!-------------------------------------------------------------------------><!------------------------------------------------------------------------->
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_interface_augment.html">Next:&nbsp;
Functions for Augmenting a Decomposition</a>&nbsp; |&nbsp; <a href="ug_interface_init.html">Previous:&nbsp;
Initialization Functions</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

790
thirdParty/Zoltan/docs/ug_html/ug_interface_mig.html vendored Normal file
View File

@ -0,0 +1,790 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Migration Interface</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">&nbsp;Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_interface_order.html">Next</a>&nbsp; |&nbsp; <a href="ug_interface_augment.html">Previous</a></i></b></div>
<h2>
<a NAME="Migration Functions"></a>Migration Functions</h2>
Zoltan's migration functions transfer object data to the processors in a
new decomposition. Data to be transferred is specified through the
import/export lists returned by
<b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>.
Alternatively, users may specify their own import/export lists.
<p>
The
migration functions can migrate objects based on their new part assignments
and/or their new processor assignments. Behavior is determined by the
<a href="ug_alg.html#MIGRATE_ONLY_PROC_CHANGES"><B>MIGRATE_ONLY_PROC_CHANGES</b></a>
parameter.
<p>
If requested, Zoltan can automatically transfer an application's data between
processors to realize a new decomposition. This functionality will be
performed as part of the call to
<b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
if the <b><a href="ug_alg.html#LB Parameters">AUTO_MIGRATE</a></b>
parameter is set to TRUE (nonzero) via a call to <b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
This approach is effective for when the data to be moved is relatively
simple. For more complicated data movement, the application can leave <b><a href="ug_alg.html#LB Parameters">AUTO_MIGRATE</a></b>
FALSE and call <b><a href="#Zoltan_Migrate">Zoltan_Migrate</a></b>
itself.
In either case, <a href="ug_query_mig.html#Migration Query Functions">routines
to pack and unpack object data</a> must be provided by the application.
See the <a href="ug_examples_mig.html#Migration Example">Migration Examples</a>
for examples with and without auto-migration.
<p>The following functions are the migration interface functions. Their
detailed descriptions can be found below.
<blockquote>
<b><a href="#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a></b>
<br><b><a href="#Zoltan_Migrate">Zoltan_Migrate</a></b>
</blockquote>
The following functions are maintained for <a href="ug_backward.html">backward compatibility</a> with previous
versions of Zoltan. These functions are applicable
only when the number of parts to be generated is equal to the number of
processors on which the parts are computed. That is,
these functions assume "parts" and "processors" are synonymous.
<blockquote>
<b><a href="#Zoltan_Compute_Destinations">Zoltan_Compute_Destinations</a></b>
<br><b><a href="#Zoltan_Help_Migrate">Zoltan_Help_Migrate</a></b>
</blockquote>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<a NAME="Zoltan_Invert_Lists"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">
int <b>Zoltan_Invert_Lists</b>
(
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_known</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>known_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>known_to_part</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>num_found</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int **<i>found_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int **<i>found_to_part</i>);&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Invert_Lists</b>(<i>zz,&nbsp; num_known, known_global_ids,
known_local_ids, known_procs, known_to_part, num_found, found_global_ids, found_local_ids,
found_procs, found_to_part</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Invert_Lists
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_known
<br>INTEGER(Zoltan_INT), INTENT(OUT) :: num_found
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_global_ids, found_global_ids
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_local_ids, found_local_ids
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_procs, found_procs
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_to_part, found_to_part
</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">
int <b>Zoltan::Invert_Lists</b>
(
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const int & <i>num_known</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>known_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>known_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>known_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>known_to_part</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int &<i>num_found</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> &<i>found_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> &<i>found_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * &<i>found_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * &<i>found_to_part</i>);&nbsp;</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Invert_Lists</b> computes inverse communication
maps useful for migrating data. It can be used in two ways:
<ul>
<li> Given a list of known off-processor objects to be received by a processor,<br>
compute a list of local objects to be sent by the processor to other
processors; or
</li>
<li> Given a list of known local objects to be sent by a processor to other processors, <br>
compute a list of off-processor objects to be received by the processor.
</li>
</ul>
For example, if each processor knows which objects it will import from other
processors, <b>Zoltan_Invert_Lists</b> computes the list of objects
each processor needs to export to other processors. If, instead, each processor
knows which objects it will export to other processors,
<b>Zoltan_Invert_Lists</b> computes the list of objects each processor
will import from other processors.
The computed lists are
allocated in Zoltan; they should not be allocated by the application before
calling <b>Zoltan_Invert_Lists</b>. These lists can be freed through a
call to <b><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
to be used in this invocation of the migration routine.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; num_known&nbsp;</i></td>
<td>The number of known objects to be received (sent) by
this processor.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; known_global_ids</i></td>
<td>An array of <i>num_known</i> global IDs of known objects to be received (sent)
by this processor.
<br>(size = <i>num_known</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>)</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; known_local_ids</i></td>
<td>An array of <i>num_known</i> local IDs of known objects to be received (sent)
by this processor.
<br>(size = <i>num_known</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; known_procs</i></td>
<td>An array of size <i>num_known</i> listing the processor IDs of the
processors that the known objects will be received from (sent to).
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; known_to_part</i></td>
<td>An array of size <i>num_known</i> listing the part numbers of the
parts that the known objects will be assigned to.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; num_found</i></td>
<td>Upon return, the number of objects that must be sent to (received from) other processors.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; found_global_ids</i></td>
<td>Upon return, an array of <i>num_found</i> global IDs of objects to be
sent (received) by this processor.
<br>(size = <i>num_found</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>)</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; found_local_ids</i></td>
<td>&nbsp;Upon return, an array of <i>num_found</i> local IDs of objects
to be sent (received) by this processor.
<br>(size = <i>num_found</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; found_procs</i></td>
<td>Upon return, an array of size <i>num_found</i> listing the processor
IDs of processors that the found objects will be sent to (received from).</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; found_to_part</i></td>
<td>An array of size <i>num_found</i> listing the part numbers of the
parts that the found objects will be assigned to.
</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<p>Note that the number of global and local ID entries (<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>) should be
set using <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
before calling <b>Zoltan_Invert_Lists</b>. All processors must have
the same values for these two parameters.
<p>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<a NAME="Zoltan_Migrate"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">
int <b>Zoltan_Migrate</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_import</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>import_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>import_to_part</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_export</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>export_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>export_to_part</i>);&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Migrate</b>(<i>zz, num_import, import_global_ids,
import_local_ids, import_procs, import_to_part,
num_export, export_global_ids, export_local_ids,
export_procs, export_to_part</i>)
<br>INTEGER(Zoltan_INT) :: Zoltan_Migrate&nbsp;
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz&nbsp;
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_import, num_export&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_to_part, export_to_part
</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">
int <b>Zoltan::Migrate</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const int & <i>num_import</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>import_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>import_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>import_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>import_to_part</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const int & <i>num_export</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>export_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>export_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>export_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>export_to_part</i>);&nbsp;</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Migrate</b> takes lists of objects to be sent
to other processors, along with the destinations of those objects, and
performs the operations necessary to send the data associated with those
objects to their destinations. <b>Zoltan_Migrate</b> performs the following
operations using the application-registered functions:
<ul>
<li>
Call <b><a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN">ZOLTAN_PRE_MIGRATE_PP_FN_TYPE</a></b> (if registered)
</li>
<li>
For each export object, call <b><a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN_TYPE</a></b> to get object sizes.
</li>
<li>
For each export object, call
<b><a href="ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN_TYPE</a></b> to load communication buffers.
</li>
<li>
Communicate buffers to destination processors.
</li>
<li>
Call <b><a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN">ZOLTAN_MID_MIGRATE_PP_FN_TYPE</a></b> (if registered).
</li>
<li>
For each imported object, call
<b><a href="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN_TYPE</a></b> to move data from the buffer into the new processor's data structures.
</li>
<li>
Call <b><a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN">ZOLTAN_POST_MIGRATE_PP_FN_TYPE</a></b> (if registered).
</li>
</ul>
<p>
Either export lists or import lists must be specified for <b>Zoltan_Migrate</b>.
Both export lists and import lists may be specified, but both are not required.
<p>
If export lists are provided,
non-NULL values for input arguments <i>import_global_ids</i>, <i>import_local_ids</i>, <i>import_procs</i>, and <i>import_to_part</i> are optional.
The values must be non-NULL only if no export lists are provided or if
the import lists are used by the application callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></a>, and
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b></a>.
If all processors pass NULL arguments for the import arrays, the value of <i>num_import</i> should be -1.
<p>
Similarly, if import lists are provided,
non-NULL values for input arguments <i>export_global_ids</i>, <i>export_local_ids</i>, <i>export_procs</i>, and <i>export_to_part</i> are optional.
The values must be non-NULL only if no import lists are provided or if
the export lists are used by the application callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></a>, and
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b></a>.
If all processors pass NULL arguments for the export arrays, the value of <i>num_export</i> should be -1.
In this case, <b>Zoltan_Migrate</b> computes the export lists based on the
import lists.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
to be used in this invocation of the migration routine.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; num_import&nbsp;</i></td>
<td>The number of objects to be imported to parts on this processor;
these objects may be stored on other processors or may be moving to new
parts within this processor.
<br> Use <i>num_import</i>=-1 if all processors do not specify import arrays.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_global_ids</i></td>
<td>An array of <i>num_import</i> global IDs of objects
to be imported to parts on this processor.
<br>(size = <i>num_import</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>).
<br>All processors may pass <i>import_global_ids</i>=NULL if
export lists are provided and
<i>import_global_ids</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></a>, and
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b></a>.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_local_ids</i></td>
<td>An array of <i>num_import</i> local IDs of objects to be imported
to parts on this processor.
<br>(size = <i>num_import</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)
<br>All processors may pass <i>import_local_ids</i>=NULL if
export lists are provided and
<i>import_local_ids</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_procs</i></td>
<td>An array of size <i>num_import</i> listing the processor IDs of
objects to be imported to parts on this processor (i.e., the source
processors).
<br>All processors may pass <i>import_procs</i>=NULL if
export lists are provided and
<i>import_procs</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_to_part</i></td>
<td>An array of size <i>num_import</i> listing the parts to which
imported objects should be assigned.
<br>All processors may pass <i>import_to_part</i>=NULL if
export lists are provided and
<i>import_to_part</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; num_export</i></td>
<td>The number of objects that were stored on this processor in the previous
decomposition that are assigned to other processors or to different
parts within this processor in the new decomposition.
<br> Use <i>num_export</i>=-1 if all processors do not specify export arrays.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_global_ids</i></td>
<td>An array of <i>num_export</i> global IDs of objects to be exported
to new parts.
<br>(size = <i>num_export</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>)
<br>All processors may pass <i>export_global_ids</i>=NULL if
import lists are provided and
<i>export_global_ids</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_local_ids</i></td>
<td>An array of <i>num_export</i> local IDs of objects to be exported to
new parts.
<br>(size = <i>num_export</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)
<br>All processors may pass <i>export_local_ids</i>=NULL if
import lists are provided and
<i>export_local_ids</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_procs</i></td>
<td>An array of size <i>num_export</i> listing the processor IDs to which
exported objects should be assigned (i.e., the destination processors).
<br>All processors may pass <i>export_procs</i>=NULL if
import lists are provided and
<i>export_procs</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_to_part</i></td>
<td>An array of size <i>num_export</i> listing the parts to which
exported objects should be assigned.
<br>All processors may pass <i>export_to_part</i>=NULL if
import lists are provided and
<i>export_to_part</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<p>Note that the number of global and local ID entries (<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>) should be
set using <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
before calling <b>Zoltan_Migrate</b>. All processors must have the same
values for these two parameters.
<br>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<a NAME="Zoltan_Compute_Destinations"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">
int <b>Zoltan_Compute_Destinations</b>
(
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_known</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>known_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>num_found</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int **<i>found_procs</i>);&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Compute_Destinations</b>(<i>zz,&nbsp; num_known, known_global_ids,
known_local_ids, known_procs, num_found, found_global_ids, found_local_ids,
found_procs</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Compute_Destinations&nbsp;
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_known
<br>INTEGER(Zoltan_INT), INTENT(OUT) :: num_found
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_global_ids, found_global_ids
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_local_ids, found_local_ids
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_procs, found_procs
</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Compute_Destinations</b> is a wrapper around
<a href="#Zoltan_Invert_Lists"><b>Zoltan_Invert_Lists</b></a> that excludes
part assignment arrays. It is maintained for backward compatibility with
previous versions of Zoltan.
<p>
<b>Zoltan_Compute_Destinations</b> assumes the
number of parts is equal to the number of processors.
The computed lists are
allocated in Zoltan; they should not be allocated by the application before
calling <b>Zoltan_Compute_Destinations</b>. These lists can be freed through a
call to <b><a href="ug_interface_lb.html#Zoltan_LB_Free_Data">Zoltan_LB_Free_Data</a></b> or
<b><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>
All arguments are analogous to those in
<a href="#Zoltan_Invert_Lists"><b>Zoltan_Invert_Lists</b></a>.
Part-assignment arrays <i>known_to_part</i> and <i>found_to_part</i> are
not included, as part and processor numbers are assumed to be the same in
<b>Zoltan_Compute_Destinations</b>.
</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<p>Note that the number of global and local ID entries (<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>) should be
set using <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
before calling <b>Zoltan_Compute_Destinations</b>. All processors must have
the same values for these two parameters.
<p>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<a NAME="Zoltan_Help_Migrate"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">
int <b>Zoltan_Help_Migrate</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_import</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>import_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_export</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>export_procs</i>);&nbsp;</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Help_Migrate</b>(<i>zz, num_import, import_global_ids,
import_local_ids, import_procs, num_export, export_global_ids, export_local_ids,
export_procs</i>)
<br>INTEGER(Zoltan_INT) :: Zoltan_Help_Migrate&nbsp;
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz&nbsp;
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_import, num_export&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs&nbsp;</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Help_Migrate</b>
is a wrapper around <a href="#Zoltan_Migrate"><b>Zoltan_Migrate</b></a>
that excludes part assignment arrays. It is maintained for backward
compatibility with previous versions of Zoltan.
<p>
<b>Zoltan_Help_Migrate</b> assumes the number of parts is equal to the
number of processors. It uses migration pre-, mid-, and post-processing
routines
<b><a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_FN">ZOLTAN_PRE_MIGRATE_FN_TYPE</a></b>,
<b><a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_FN">ZOLTAN_MID_MIGRATE_FN_TYPE</a></b>, and
<b><a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_FN">ZOLTAN_POST_MIGRATE_FN_TYPE</a></b>, respectively, which also exclude part assignment arrays.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>
All arguments are analogous to those in
<a href="#Zoltan_Migrate"><b>Zoltan_Migrate</b></a>.
Part-assignment arrays <i>import_to_part</i> and <i>export_to_part</i> are
not included, as part and processor numbers are assumed to be the same in
<b>Zoltan_Help_Migrate</b>.
</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<br>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_interface_order.html">Next:&nbsp;
Ordering Interface</a>&nbsp; |&nbsp; <a href="ug_interface_augment.html">Previous:&nbsp;
Functions for Augmenting a Decomposition</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

591
thirdParty/Zoltan/docs/ug_html/ug_interface_order.html 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
------->
<!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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Ordering Interface</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_interface_color.html">Next</a>&nbsp; |&nbsp; <a href="ug_interface_mig.html">Previous</a></i></b></div>
<h2>
<a NAME="Ordering Functions"></a>Ordering Functions</h2>
Zoltan provides functions for ordering a set of objects,
typically given as a graph (which may correspond to a sparse matrix).
The following functions are the ordering interface functions in Zoltan.
The first is the main function, and the others are accessor functions
that should only be called after <a href="#Zoltan_Order">Zoltan_Order</a>.
<blockquote>
<ul>
<li>
<li><b><a href="#Zoltan_Order">Zoltan_Order</a></b></li>
<li><b><a href="#Zoltan_Order_Get_Num_Blocks">Zoltan_Order_Get_Num_Blocks</a></b></li>
<li><b><a href="#Zoltan_Order_Get_Block_Bounds">Zoltan_Order_Get_Block_Bounds</a></b></li>
<li><b><a href="#Zoltan_Order_Get_Block_Size">Zoltan_Order_Get_Block_Size</a></b></li>
<li><b><a href="#Zoltan_Order_Get_Block_Parent">Zoltan_Order_Get_Block_Parent</a></b></li>
<li><b><a href="#Zoltan_Order_Get_Num_Leaves">Zoltan_Order_Get_Num_Leaves</a></b></li>
<li><b><a href="#Zoltan_Order_Get_Block_Leaves">Zoltan_Order_Get_Block_Leaves</a></b></li>
</ul>
</blockquote>
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Order"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Order</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_gid_entries</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_obj</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR </a></b><i>global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR </a></b> <i>rank</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;)
</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
<td>FUNCTION <b>Zoltan_Order</b>(<i>zz, num_gid_entries</i>,
<i>num_obj, global_ids</i>, <i>rank, iperm</i>)
<br>INTEGER(Zoltan_INT) :: Zoltan_Order
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_gid_entries
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_obj
<br>INTEGER(Zoltan_INT) :: global_ids(*)
<br>INTEGER(Zoltan_INT) :: rank(*)
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Order</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_gid_entries</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_obj</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR </a></b><i>global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR </a></b> <i>rank</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;)
</td>
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Order </b>invokes the ordering routine specified
by the&nbsp; <i><a href="ug_order.html#ORDER_METHOD">ORDER_METHOD</a></i> parameter.
Results of the ordering is returned in the array <i>rank </i>.
<p>
<li>
<i>rank[i]</i>
gives the rank of <i>global_ids[i] </i>in the computed ordering, which is a number between 0 and N-1 where N is the overall number of objects across all the processors. (Note: This will change in future versions. A permuted set of GIDs will be returned instead.)
</li>
The arrays
<i>global_ids, rank,</i>
should all be allocated by the application before
<b>Zoltan_Order</b> is
called. Each array must have space for (at least)
<i>num_obj </i>elements,
where <i>num_obj </i>is the number of objects the user want to know informations about.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
to be used in this invocation of the load-balancing routine.</td>
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>&nbsp;&nbsp;&nbsp; <i>num_gid_entries</i></td>
<td>Input: the number of array entries used to describe a single
global ID.&nbsp; This value is the maximum value over all processors of
the parameter <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td>&nbsp;&nbsp;&nbsp; <i>num_obj</i></td>
<td NOSAVE>Number of objects for which we want to know the ordering. Objects may be non-local.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; global_ids</i></td>
<td>An array of global IDs of objects for which we want to know the
ordering on this processor. Size of this array must be <i>num_obj</i>.
<br>Objects may be non-local. Objects IDs may be repeated on several
processor.</td> </tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; rank</i></td>
<td>Upon return, an array of length <i>num_obj </i>containing the rank
of each object in the computed ordering. When rank[i] = j, that means that
the object corresponding to
<i>global_ids[i]
</i>is the<i> j</i>th object
in the ordering. (This array corresponds directly to the <i>perm </i>array
in METIS and the <i>order</i> array in ParMETIS.) Note that the rank may
refer to either a local or a global ordering, depending on <a href="ug_order.html#ORDER_TYPE">ORDER_TYPE</a>.&nbsp;
Memory for this array must have been allocated before <b>Zoltan_Order</b> is
called.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<h3>Accessors</h3>
Zoltan primarily supports nested dissection orderings, which are
typically used to reduce fill in direct solvers. For this use case, it is
important to get additional information (the separators).
The accessor functions below define the Zoltan interface.
Note that these functions should be called after
<a href="#Zoltan_Order">Zoltan_Order</a>.
<!------------------------------------------------------------------------->
<a NAME="Zoltan_Order_Get_Num_Blocks"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Order_Get_Num_Blocks</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>)
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Order_Get_Num_Blocks</b> ()
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Order_Get_Num_Blocks </b> returns the number of subdomains (or column blocks) computed during the ordering. For a Nested Dissection based ordering method, it corresponds to the sum of the separators and the subgraphs of the lowest level. For example, after one bisection the number of blocks is three.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
which has been used in the ordering routine.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td>The number of <i>blocks</i> (subdomains).</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Order_Get_Block_Bounds"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Order_Get_Block_Bounds</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>block_id</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>first</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>last</i>)
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Order_Get_Block_Bounds</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>block_id</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int &<i>first</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int &<i>last</i>)
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Order_Get_Block_Bounds </b> gives the
boundaries of the given block. The <i>first</i> and <i>last</i>
parameters contain upon return the indices of the begin and the end of
the block. These indices are from the global continuous numbering
between 1 and N-1 of the N distributed objects.
<br>&nbsp;
<table WIDTH="100%" NOSAVE > <tr> <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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
which has been used in the ordering routine.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; block_id</i></td>
<td>The number of the block we want informations on.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; first</i></td>
<td>Upon return, pointer to the value of the begining of the block.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; last</i></td>
<td>Upon return, pointer to the value of the end of the block.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Order_Get_Block_Size"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Order_Get_Block_Size</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>block_id</i>)
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Order_Get_Block_Size</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>block_id</i>)
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Order_Get_Block_Size </b> returns the number of objects in the block <i>block_id</i>.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
which has been used in the ordering routine.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; block_id</i></td>
<td>The indice of the block we want to know the size.</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td>The number of objects in this given <i>block</i>.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Order_Get_Block_Parent"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Order_Get_Block_Parent</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>block_id</i>)
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Order_Get_Block_Parent</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>block_id</i>)
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Order_Get_Block_Parent </b> returns the
number (id) of the parent block in the elimination tree. The value is
-1 for the root of the tree.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
which has been used in the ordering routine.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; block_id</i></td>
<td>The indice of the block we want to know the size.</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td>The number (id) of the parent block in the elimination tree. The
value is -1 for the root of the tree.</td> </tr> </table>
<p>
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Order_Get_Num_Leaves"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">int <b>Zoltan_Order_Get_Num_Leaves</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>)
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">int <b>Zoltan::Order_Get_Num_Leaves</b> ()
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Order_Get_Num_Leaves </b> returns the number of leaves in the elimination tree.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
which has been used in the ordering routine.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>
<td>The number of leaves in the elimination tree.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<!------------------------------------------------------------------------->
<hr WIDTH="100%"><a NAME="Zoltan_Order_Get_Block_Leaves"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>
<td WIDTH="85%">void <b>Zoltan_Order_Get_Block_Leaves</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>leaves</i>)
</tr>
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>
<td WIDTH="85%">void <b>Zoltan::Order_Get_Block_Leaves</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>leaves</i>)
</tr>
</table>
<hr WIDTH="100%"><b>Zoltan_Order_Get_Block_Leaves </b> get the indices
of the blocks that are leaves in the elimination tree.
<br>&nbsp;
<table WIDTH="100%" NOSAVE > <tr> <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 the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
which has been used in the ordering routine.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; leaves</i></td>
<td>Array of indices of the blocks that are leaves in the elimination. The last element of this array is -1. The array must be of size <i>number of leave + 1</i> and must be allocated by the user before the call.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_interface_color.html">Next:&nbsp;
Coloring Functions</a>&nbsp; |&nbsp; <a href="ug_interface_mig.html">Previous:&nbsp;
Migration Functions</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

367
thirdParty/Zoltan/docs/ug_html/ug_intro.html vendored Normal file
View File

@ -0,0 +1,367 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Introduction</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_usage.html">Next</a>&nbsp; |&nbsp; <a href="ug.html">Previous</a></i></b></div>
<!---------------------------------------------------------------------------->
<h2>
<a NAME="Introduction"></a>Introduction</h2>
<blockquote>
<a href="#Motivation">Project Motivation</a>
<br><a href="#Tools">The Zoltan Toolkit</a>
<br><a href="#Terms">Terminology</a>
<br><a href="#Design">Zoltan Design</a>
</blockquote>
<!---------------------------------------------------------------------------->
<a NAME="Motivation"></a><hr><h2>Project Motivation</h2>
Over the past decade, parallel computers have been used with great success in
many scientific simulations. While differing in their numerical methods and
details of implementation, most applications successfully parallelized to date
are "static" applications. Their data structures and memory usage do not
change during the course of the computation. Their inter-processor
communication patterns are predictable and non-varying. And their processor
workloads are predictable and roughly constant throughout the simulation.
Traditional finite difference and finite element methods are examples of
widely used static applications.
<p>
However, increasing use of "dynamic" simulation techniques is creating new
challenges for developers of parallel software. For example, adaptive finite
element methods refine localized regions the mesh and/or adjust the order of
the approximation on individual elements to obtain a desired accuracy in the
numerical solution. As a result, memory must be allocated dynamically to
allow creation of new elements or degrees of freedom. Communication patterns
can vary as refinement creates new element neighbors. And localized
refinement can cause severe processor load imbalance as elemental and
processor work loads change throughout a simulation.
<p>
Particle simulations and crash simulations are other examples of dynamic
applications. In particle simulations, scalable parallel performance depends
upon a good assignment of particles to processors; grouping physically close
particles within a single processor reduces inter-processor communication.
Similarly, in crash simulations, assignment of physically close surfaces to a
single processor enables efficient parallel contact search. In both cases,
data structures and communication patterns change as particles and surfaces
move. Re-partitioning of the particles or surfaces is needed to maintain
geometric locality of objects within processors.
<p>
We developed the Zoltan library to simplilfy many of the difficulties
arising in dynamic applications. Zoltan is a collection of data management
services for unstructured, adaptive and dynamic applications.
It includes a
suite of parallel partitioning algorithms, data migration tools, parallel
graph coloring tools, distributed
data directories, unstructured communication services, and dynamic memory
management tools. Zoltan's data-structure neutral design allows it to be used
by a variety of applications without imposing restrictions on application data
structures. Its object-based interface provides a simple and inexpensive way
for application developers to use the library and researchers to make new
capabilities available under a common interface.
<p>
<!---------------------------------------------------------------------------->
<a NAME="Tools"></a><hr><h2>The Zoltan Toolkit</h2>
The Zoltan Library contains a number of tools that simplify the development
and improve the performance of parallel, unstructured and adaptive
applications. The library is organized as a toolkit, so that application
developers can use as little or as much of the library as desired. The major
packages in Zoltan are listed below.
<ul>
<li>
A suite of <a href="ug_alg.html">dynamic load balancing and parallel
repartitioning</a> algorithms, including geometric, hypergraph and graph
methods;
switching between algorithms is easy, allowing straightforward comparisons of
algorithms in applications.
</li>
<li>
<a href="ug_interface_mig.html">Data migration tools</a> for moving data from
old partitions to new one.
</li>
<li>
<a href="ug_color.html">Parallel graph coloring tools</a> with both distance-1
and distance-2 coloring.
</li>
<li>
<a href="../ug_html/ug_util_dd.html">Distributed data directories</a>:
scalable (in memory and computation) algorithms for locating needed
off-processor data.
</li>
<li>
An <a href="../ug_html/ug_util_comm.html">unstructured communication
package</a> that insulates users from the details of message sends and
receives.
</li>
<li>
<a href="../ug_html/ug_util_mem.html">Dynamic memory management tools</a>
that simplify dynamic memory debugging on state-of-the-art parallel
computers.
</li>
<li>
A sample application <a href="../dev_html/dev_driver.html"><i>zdrive</i></a>.
It allows algorithm developers
to test changes to Zoltan without having to run Zoltan in
a large application code. Application developers can use the <i>zdrive</i>
code to see examples of function calls to Zoltan and the implementation of
query functions.
</li>
</ul>
<!---------------------------------------------------------------------------->
<a NAME="Terms"></a><hr><h2>Terminology</h2>
Our design of Zoltan does not restrict it to any particular type of
application. Rather, Zoltan operates on uniquely identifiable data items that
we call <i>objects</i>. For example, in finite element applications, objects
might be elements or nodes of the mesh. In particle applications, objects
might be particles. In linear solvers, objects might be matrix rows or
non-zeros.
<p>
Each object must have a unique <i>global identifier (ID)</i>
represented as an array
of unsigned integers. Common choices include global numbers of elements
(nodes, particles, rows, and so on) that already exist in many applications,
or a structure consisting of an owning processor number and the object's
local-memory index. Objects might also have local (to a processor) IDs that
do not have to be unique globally. Local IDs such as addresses or local-array
indices of objects can improve the performance (and convenience) of Zoltan's
interface to applications.
<p>
We use a simple example to illustrate the above terminology.
On the left side of the figure
<a href="#Terms Figure">below</a>, a simple finite element mesh is presented.
<p>
<center><a NAME="Terms Figure"></a><img SRC="figures/HGFigure.gif"></center>
<p>
The blue and red shading indicates the mesh is partitioned for two
processors. An application must
provide information about the current mesh and partition to Zoltan.
If, for example,
the application wants Zoltan to perform operations on the elements of the
mesh,
it must provide information about the elements when Zoltan asks for object
information.
<p>
In this example, the elements have unique IDs
assigned to them, as shown by the letters in the elements. These unique
letters can be used as global IDs in Zoltan. In addition, on each
processor, local numbering information may be available.
For instance, the elements owned by a processor may be stored in arrays
in the processor's memory. An element's local array index may be provided to
Zoltan as a local ID.
<p>
For geometric algorithms, the application must provide coordinate
information to Zoltan. In this example, the coordinates of the mid-point of
an element are used.
<p>
For hypergraph- and graph-based algorithms,
information about the connectivity of
the objects must be provided to Zoltan. In this example, the application may
consider elements connected if they share a face. A hypergraph representing
this problem is then shown to the right of the mesh. A <i>hyperedge</i> exists
for each object (squares labeled with lower-case letters corresponding
to the related object). Each hyperedge connects
the object and all of its face neighbors. The hyperedges are passed to
Zoltan with a label (in this example, a lower-case letter) and a list of
the object IDs in that hyperedge.
<p>
Graph connections, or <i>edges</i>, across element faces may also specified.
Connectivity information is passed to Zoltan by specifying a neighbor list for
an object. The neighbor list consists of the global IDs of neighboring objects
and the processor(s) currently owning those objects. Because relationships
across faces are bidirectional, the graph edge lists and hypergraph hyperedge
lists are nearly identical. If, however, information flowed to, say, only
the north and east edge neighbors of an element, the hypergraph model would
be needed, as the graph model can represent only bidirectional relationships.
In this case, the hyperedge contents would include only the north and east
neighbors; they would exclude south and west neighbors.
<p>
The table below summarizes the information provided to Zoltan by an
application for this finite element mesh. Information about the objects
includes their global and local IDs, geometry data, hypergraph data,
and graph data.
<p>
<table Border="2" Width="100%">
<tr>
<td></td>
<td COLSPAN="2"><center>Object IDs</center></td>
<td><center>Geometry Data</center></td>
<td COLSPAN="2"><center>Graph Data</center></td>
</tr>
<tr>
<td><center>Processor</center></td>
<td><center>Global</center></td>
<td><center>Local</center></td>
<td><center>(coordinates)</center></td>
<td><center>Neighbor Global ID List</center></td>
<td><center>Neighbor Processor List</center></td>
</tr>
<tr>
<td><center>Red</center></td>
<td><center>A</center></td>
<td><center>0</center></td>
<td><center>(2,10)</center></td>
<td><center>B,D</center></td>
<td><center>Blue</center></td>
</tr>
<tr>
<td><center>Blue</center></td>
<td><center>B</center></td>
<td><center>0</center></td>
<td><center>(1,7)</center></td>
<td><center>A,C,D</center></td>
<td><center>Red,Blue,Blue</center></td>
</tr>
<tr>
<td><center></center></td>
<td><center>C</center></td>
<td><center>1</center></td>
<td><center>(1,5)</center></td>
<td><center>B,E,F</center></td>
<td><center>Blue,Blue,Blue</center></td>
</tr>
<tr>
<td><center></center></td>
<td><center>D</center></td>
<td><center>2</center></td>
<td><center>(3,7)</center></td>
<td><center>A,B,E</center></td>
<td><center>Red,Blue,Blue</center></td>
</tr>
<tr>
<td><center></center></td>
<td><center>E</center></td>
<td><center>3</center></td>
<td><center>(3,5)</center></td>
<td><center>C,D,F</center></td>
<td><center>Blue,Blue,Blue</center></td>
</tr>
<tr>
<td><center></center></td>
<td><center>F</center></td>
<td><center>4</center></td>
<td><center>(2,2)</center></td>
<td><center>C,E</center></td>
<td><center>Blue,Blue</center></td>
</tr>
</table>
<table border="2" width="50%">
<tr>
<td COLSPAN="2"><center>Hyperedge Data</center></td>
</tr>
<tr>
<td><center>Hyperedge ID</center></td>
<td><center>Hyperedge contents</center></td>
</tr>
<tr>
<td><center>a</center></td>
<td><center>A,B,D</center></td>
</tr>
<tr>
<td><center>b</center></td>
<td><center>A,B,C,D</center></td>
</tr>
<tr>
<td><center>c</center></td>
<td><center>B,C,E,F</center></td>
</tr>
<tr>
<td><center>d</center></td>
<td><center>A,B,D,E</center></td>
</tr>
<tr>
<td><center>e</center></td>
<td><center>C,D,E,F</center></td>
</tr>
<tr>
<td><center>f</center></td>
<td><center>C,E,F</center></td>
</tr>
</table>
<!---------------------------------------------------------------------------->
<a NAME="Design"></a><hr><h2>Zoltan Design</h2>
To make Zoltan easy to use, we do not impose any particular data structure on
an application, nor do we require an application to build a particular data
structure for Zoltan. Instead, Zoltan uses a
<a href="ug_query.html">callback function interface</a>, in
which Zoltan queries the application for needed data. The application must
provide simple functions that answer these queries.
<p>
To keep the application interface simple, we use a small set of
<a href="ug_query.html">callback functions</a>
and make them easy to write by requesting only information that is
easily accessible to applications. For example, the most basic partitioning
algorithms
require only four callback functions. These functions return the number of
objects owned by a processor, a list of weights and IDs for owned objects, the
problem's dimensionality, and a given object's coordinates. More
sophisticated graph-based partitioning algorithms require only two additional
callback functions, which return the number of edges per object and edge lists
for objects.
<!---------------------------------------------------------------------------->
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_usage.html">Next:&nbsp;
Zoltan Usage</a>&nbsp; | <a href="ug.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>

140
thirdParty/Zoltan/docs/ug_html/ug_order.html vendored Normal file
View File

@ -0,0 +1,140 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Ordering Algorithms</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_order_parmetis.html">Next</a>&nbsp; |&nbsp; <a href="ug_alg_hier.html">Previous</a></i></b></div>
<!---------------------------------------------------------------------------->
<h2>
<a NAME="Ordering Algorithms"></a>Ordering Algorithms</h2>
The following graph (sparse matrix) ordering algorithms are currently included in the Zoltan toolkit:
<blockquote>
<a href="ug_order_parmetis.html">Nested dissection by METIS/ParMETIS </a><br>
<a href="ug_order_ptscotch.html">Nested dissection by Scotch/PT-Scotch</a><br>
<a href="ug_order_local_hsfc.html">Local ordering with Hilbert space filling curves</a>
</blockquote>
These methods produce orderings for various applications (e.g., reducing fill in sparse matrix factorizations).
Ordering is accessed through calls to
<b><a href="ug_interface_order.html#Zoltan_Order">Zoltan_Order</a></b>.
<p><!---------------------------------------------------------------------------->
<h3>
<b>Third-party libraries</b>
</h3>
Currently, most ordering in Zoltan is provided through the third-party libraries METIS/ParMETIS and PT-Scotch.
The one exception is the local Hilbert space filling curve ordering.
To use the other methods, a third-party library must be present.
<h3>
<a NAME="Order Parameters"></a>
<hr><b>Ordering Parameters</b></h3>
While the overall behavior of Zoltan is controlled by <a href="ug_param.html">general
Zoltan parameters</a>, the behavior of each ordering method is controlled
by parameters specific to ordering which are also set by calls to <b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
Many of these parameters are specific to individual ordering algorithms,
and are listed in the descriptions of the individual algorithms.&nbsp;
However, several have meaning across multiple ordering algorithms. These
parameters are described below.
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr VALIGN=TOP>
<td VALIGN=TOP><b>Parameters:</b></td>
<td></td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="ORDER_METHOD"></a>&nbsp;&nbsp; <i>ORDER_METHOD</i></td>
<td>The order algorithm used by Zoltan is specified by this parameter.
Valid values are&nbsp;
<blockquote>
"METIS" (sequential <a href="ug_order_parmetis.html">nodal nested dissection by METIS</a>),
<br>"PARMETIS" (parallel <a href="ug_order_parmetis.html">nodal nested dissection by ParMETIS </a>),
<br>"SCOTCH" (sequential ordering using <a href="ug_order_ptscotch.html">Scotch</a>),
<br>"PTSCOTCH" (parallel ordering using <a href="ug_order_ptscotch.html">PT-Scotch</a>),
<br>"LOCAL_HSFC" (local ordering using <a href="ug_order_local_hsfc.html">Hilbert space filling curves</a>), and
<br>"NONE" (for no ordering).
</blockquote>
</td>
</tr>
<tr VALIGN=TOP>
<td VALIGN=TOP><a NAME="Default_Parameter_Values"></a><b>Default Values:</b></td>
<td></td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td><i>ORDER_METHOD</i> = PARMETIS (with MPI), METIS (when no MPI)</td>
</tr>
</table>
<p><!---------------------------------------------------------------------------->
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_order_parmetis.html">Next:&nbsp;
Nested dissection by ParMETIS</a>&nbsp; |&nbsp; <a href="ug_alg_hier.html">Previous:&nbsp;
Hybrid Hierarchical Partitioning</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

133
thirdParty/Zoltan/docs/ug_html/ug_order_local_hsfc.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
------->
<!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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Local Ordering with HSFC</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_color.html">Next</a>&nbsp; |&nbsp; <a href="ug_order_ptscotch.html">Previous</a></i></b></div>
<h2>
<a NAME="LOCAL_HSFC"></a>Local Ordering with Hilbert Space Filling Curves (HSFC)</h2>
This is a local geometric ordering method that uses Hilbert space filling curves
to order the vertices located at specified coordinates. This method assumes the
data to be ordered is local to the process and the query functions should
reflect this.
<p>
For more information on the HSFC algorithm, see the
<a href="ug_alg_hsfc.html">HSFC algorithm documentation</a>.
<br>&nbsp;
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP><b>Order_Method String:</b></td>
<td><b>LOCAL_HSFC</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>Currently none defined.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td NOSAVE>
<b><a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b>
</td>
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_color.html">Next:&nbsp;
Coloring Algorithms</a> |&nbsp; <a href="ug_order_ptscotch.html">Previous:&nbsp; Ordering by PT-Scotch</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

147
thirdParty/Zoltan/docs/ug_html/ug_order_parmetis.html vendored Normal file
View File

@ -0,0 +1,147 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Nested Dissection by ParMETIS</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_order_ptscotch.html">Next</a>&nbsp; |&nbsp; <a href="ug_order.html">Previous</a></i></b></div>
<h2>
<a NAME="METIS"></a>Nested Dissection by METIS/ParMETIS</h2>
Nested Dissection (ND) is a popular method to compute fill-reducing orderings
for sparse matrices. It can also be used for other ordering purposes.&nbsp;
The algorithm recursively finds a separator (bisector) in a graph,
orders the nodes in the two subsets first, and nodes in the separator last.
In METIS/ParMETIS, the recursion is stopped when the graph is smaller than
a certain size, and some version of minimum degree ordering is applied
to the remaining graph.
<p>METIS computes a (local) ordering of the objects (currently only for serial runs), while
ParMETIS performs a global ordering of all the objects. ParMETIS currently
(version 3.1, supported by Zoltan) requires that the number of processors is a power
of two.
<p>
<!--
** NOT TRUE at the moment
The generic name for this method is NODEND.
If GRAPH_TYPE=GLOBAL
ParMETIS is called, but if it is LOCAL, METIS is called. Alternatively,
the user can simply set ORDER_METHOD to METIS or PARMETIS.
-->
If ORDER_METHOD=PARMETIS
ParMETIS is called, but if it is METIS, METIS is called.
<br>&nbsp;
<br>&nbsp;
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP><b>Order_Method String:</b></td>
<td><b>METIS or PARMETIS</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; See <a href="ug_alg_parmetis.html">ParMETIS</a>.</td>
<td>Note that the PARMETIS options are ignored when METIS is called.&nbsp;</td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td NOSAVE>
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_F
N</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_F
N</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a></b>
</td>
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_order_ptscotch.html">Next:&nbsp;
Ordering by PT-Scotch</a> |&nbsp; <a href="ug_order.html">Previous:&nbsp; Ordering Algorithms</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

151
thirdParty/Zoltan/docs/ug_html/ug_order_ptscotch.html vendored Normal file
View File

@ -0,0 +1,151 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Nested Dissection by Scotch</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_order_local_hsfc.html">Next</a>&nbsp; |&nbsp; <a href="ug_order_parmetis.html">Previous</a></i></b></div>
<h2>
<a NAME="PT-Scotch"></a>Nested Dissection by Scotch</h2> Nested
Dissection is a popular method to compute fill-reducing orderings for
graphs and sparse matrices. It can also be used for other ordering
purposes. The algorithm recursively finds a separator (bisector) in a
graph, orders the nodes in the two subsets first, and nodes in the
separator last.
<p>
Scotch is a library for ordering and partitioning, developed at LaBRI
in Bordeaux, France. PT-Scotch is the parallel module in Scotch. (We
use the names Scotch and PT-Scotch interchangeably.) Scotch is a
third-party library in Zoltan and should be obtained separately from
the <a href="https://www.labri.fr/perso/pelegrin/scotch/">Scotch web
site</a>. Zoltan supports version 5.1 of Scotch.
<p>
If the parameter <a href="ug_order.html#ORDER_METHOD">ORDER_METHOD</a> is
set to SCOTCH, the sequential version of Scotch is called.
If the parameter <a href="ug_order.html#ORDER_METHOD">ORDER_METHOD</a> is
set to PTSCOTCH, the parallel version of Scotch (PT-Scotch) is called.
</p>
<table WIDTH="100%" NOSAVE >
<tr>
<td VALIGN=TOP><b>Order_Method String:</b></td>
<td><b>PTSCOTCH or SCOTCH</b></td>
</tr>
<tr>
<td><b>Parameters:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; SCOTCH_METHOD</td>
<td>For now, always set to NODEND</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; SCOTCH_STRAT</td>
<td>The Scotch strategy string; see the Scotch documentation.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; SCOTCH_STRAT_FILE</td>
<td>A file that contains an arbitrary long Scotch strategy string; see the Scotch documentation.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Required Query Functions:</b></td>
<td></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN</a></b></td>
</tr>
<tr>
<td></td>
<td><b><a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN</a></b>
</td>
</tr>
<tr VALIGN=TOP>
<td></td>
<td NOSAVE>
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_F
N</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_FN">ZOLTAN_NUM_EDGES_FN</a></b>
<br>
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_F
N</a></b> or
<b><a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_FN">ZOLTAN_EDGE_LIST_FN</a></b>
</td>
</tr>
</table>
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_order_local_hsfc.html">Next:&nbsp;
Local Ordering with HSFC</a> |&nbsp; <a href="ug_order_parmetis.html">Previous:&nbsp; Ordering by ParMetis</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

336
thirdParty/Zoltan/docs/ug_html/ug_param.html vendored Normal file
View File

@ -0,0 +1,336 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Algorithms</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_alg.html">Next</a>&nbsp; |&nbsp; <a
href="ug_query_mig.html">Previous</a></i></b></div>
<!---------------------------------------------------------------------------->
<h2>Zoltan Parameters and Output Levels</h2>
The behavior of Zoltan is controlled by several <a
href="#General_Parameters">parameters
</a>and
<a href="#Debug%20Levels%20in%20Zoltan">debugging-output
levels</a>. These parameters can be set by calls to <b><a
href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
Reasonable <a href="#Default_Parameter_Values">default values</a> for
all
parameters are specified by Zoltan. Many of the parameters are specific
to individual algorithms, and are listed in the descriptions of those
algorithms.&nbsp;
However, the parameters below have meaning across the entire library.
<h3><a name="General_Parameters"></a>
<hr><b>General Parameters</b></h3>
The following parameters apply to the entire Zoltan library. While
reasonable
<a href="#Default_Parameter_Values">default
values</a> for all parameters are specified by Zoltan, applications can
change these values through calls to <b><a
href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
<br>
&nbsp;
<table nosave="" width="100%">
<tbody>
<tr valign="top">
<td valign="top"><b>Parameters:</b></td>
<td><br>
</td>
</tr>
<tr nosave="" valign="top">
<td nosave=""><a name="NUM_GID_ENTRIES"></a>&nbsp;&nbsp;&nbsp; <i><a
href="ug_usage.html#Data%20Types%20for%20Object%20IDs">NUM_GID_ENTRIES</a></i></td>
<td>The number of unsigned integers that should be used to
represent a
global identifier (ID). Values greater than zero are accepted.&nbsp;</td>
</tr>
<tr nosave="" valign="top">
<td nosave=""><a name="NUM_LID_ENTRIES"></a>&nbsp;&nbsp;&nbsp; <i><a
href="ug_usage.html#Data%20Types%20for%20Object%20IDs">NUM_LID_ENTRIES</a></i></td>
<td>The number of unsigned integers that should be used to
represent a
local identifier (ID). Values greater than or equal to zero are
accepted.&nbsp;</td>
</tr>
<tr valign="top">
<td valign="top">&nbsp;&nbsp;&nbsp;<i> <a
href="#Debug%20Levels%20in%20Zoltan">DEBUG_LEVEL</a></i></td>
<td>An integer indicating how much debugging information is
printed by
Zoltan.&nbsp; Higher values of<i> <a
href="#Debug%20Levels%20in%20Zoltan">DEBUG_LEVEL</a></i>
produce more output and potentially slow down Zoltan's
computations.&nbsp;
The least output is produced when <i><a
href="#Debug%20Levels%20in%20Zoltan">DEBUG_LEVEL</a></i>=
0.&nbsp; <i><a href="#Debug%20Levels%20in%20Zoltan">DEBUG_LEVEL</a></i>&nbsp;
primarily controls Zoltan's behavior; most algorithms have their own
parameters
to control their output level. Values used within Zoltan are listed <a
href="#Debug%20Levels%20in%20Zoltan">below</a>.
<br>
Note:&nbsp; Because some debugging levels use processor
synchronization,
all processors should use the same value of <i><a
href="#Debug%20Levels%20in%20Zoltan">DEBUG_LEVEL</a></i>.</td>
</tr>
<tr nosave="" valign="top">
<td nosave=""><a name="Debug_Processor"></a><i>&nbsp;&nbsp;&nbsp;
DEBUG_PROCESSOR</i></td>
<td>Processor number from which trace output should be printed
when <i><a href="#Debug%20Levels%20in%20Zoltan">DEBUG_LEVEL</a></i>
is 5.</td>
</tr>
<tr nosave="" valign="top">
<td nosave=""><a name="DEBUG_MEMORY"></a><i>&nbsp;&nbsp;&nbsp;
DEBUG_MEMORY</i></td>
<td>Integer indicating the amount of low-level debugging
information about
memory-allocation should be kept by Zoltan's <a href="ug_util_mem.html">Memory
Management utilities</a>. Valid values are 0, 1, 2, and 3.</td>
</tr>
<tr nosave="" valign="top">
<td><a name="OBJ_WEIGHT_DIM"></a><i>&nbsp;&nbsp;&nbsp;
OBJ_WEIGHT_DIM</i></td>
<td nosave="">The number of weights (to be supplied by the user
in a query function) associated with an object. If this parameter
is zero, all objects have equal weight. Some algorithms may not support
multiple (multidimensional) weights.</td>
</tr>
<tr nosave="" valign="top">
<td><a name="EDGE_WEIGHT_DIM"></a><i>&nbsp;&nbsp;&nbsp;
EDGE_WEIGHT_DIM</i></td>
<td nosave="">The number of weights associated with an edge. If
this parameter
is zero, all edges have equal weight. Many algorithms do not support
multiple
(multidimensional) weights.</td>
</tr>
<tr valign="top">
<td><a name="TIMER"></a><i>&nbsp;&nbsp;&nbsp; TIMER</i></td>
<td>The timer with which you wish to measure time. Valid choices
are <i>wall
</i>(based
on <i>MPI_Wtime)</i>,<i> cpu </i>(based on the ANSI C library
function
<i>clock</i>)<i>, </i>and <i>user</i>.&nbsp; The resolution may
be poor,
as low as 1/60th of a second, depending upon your platform.</td>
</tr>
<tr valign="top">
<td valign="top"><a name="Default_Parameter_Values"></a><b>Default
Values:</b></td>
<td><br>
</td>
</tr>
<tr valign="top">
<td><br>
</td>
<td><i>NUM_GID_ENTRIES</i> = 1</td>
</tr>
<tr valign="top">
<td><br>
</td>
<td><i>NUM_LID_ENTRIES</i> = 1</td>
</tr>
<tr valign="top">
<td><br>
</td>
<td><i>DEBUG_LEVEL</i> = 1</td>
</tr>
<tr valign="top">
<td><br>
</td>
<td><i>DEBUG_PROCESSOR</i> = 0</td>
</tr>
<tr valign="top">
<td><br>
</td>
<td><i>DEBUG_MEMORY</i> = 1</td>
</tr>
<tr nosave="" valign="top">
<td><br>
</td>
<td nosave=""><i>OBJ_WEIGHT_DIM = 0</i></td>
</tr>
<tr valign="top">
<td><br>
</td>
<td><i>EDGE_WEIGHT_DIM = 0</i></td>
</tr>
<tr valign="top">
<td><br>
</td>
<td><i>TIMER</i> = wall</td>
</tr>
</tbody>
</table>
<h3>
<a name="Debug Levels in Zoltan"></a>
<hr>Debugging Levels in Zoltan</h3>
The <i>DEBUG_LEVEL</i> parameter determines how much debugging
information
is printed to <i>stdout</i> by Zoltan.&nbsp; It is set by a call to <b><a
href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.&nbsp;
Higher values of<i> DEBUG_LEVEL</i> produce more output and can slow
down
Zoltan's computations, especially when the output is printed by one
processor
at a time.&nbsp; The least output is produced when <i>DEBUG_LEVEL</i>
=
0.
<p>Descriptions of the output produced by Zoltan for each value of <i>DEBUG_LEVEL
</i>are
included below.&nbsp; For a given <i>DEBUG_LEVEL</i> value<i> n,</i>
all
output for values less than or equal to<i> n</i> is produced.
</p>
<p>Some high debugging levels use processor synchronization to force
processors
to write one-at-a-time.&nbsp;&nbsp; For example, when <i>DEBUG_LEVEL</i>
is greater than or equal to eight, each processor writes its list in
turn
so that the lists from all processors are not jumbled together in the
output.&nbsp;
This synchronization requires all processors to use the same value of <i>DEBUG_LEVEL</i>.
<br>
&nbsp;
<table nosave="" width="100%">
<tbody>
<tr valign="top">
<td valign="top"><b><i>DEBUG_LEVEL&nbsp;</i></b></td>
<td><b>Output Produced</b></td>
</tr>
<tr nosave="" valign="top">
<td nosave="">&nbsp;&nbsp;&nbsp; 0</td>
<td>Quiet mode; no output unless an error or warning is produced.</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; 1</td>
<td nosave="">Values of all parameters set by <b><a
href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>
and used by Zoltan.</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; 2</td>
<td nosave="">Timing information for Zoltan's main routines.</td>
</tr>
<tr nosave="" valign="top">
<td nosave="">&nbsp;&nbsp;&nbsp; 3</td>
<td nosave="">Timing information within Zoltan's algorithms
(support by algorithms
is optional).</td>
</tr>
<tr nosave="" valign="top">
<td nosave=""><i>&nbsp;&nbsp;</i>&nbsp; 4</td>
<td><br>
</td>
</tr>
<tr nosave="" valign="top">
<td valign="top">&nbsp;&nbsp;&nbsp; 5</td>
<td nosave="">Trace information (enter/exit) for major Zoltan
interface routines
(printed by the processor specified by the <i><a
href="#Debug_Processor">DEBUG_PROCESSOR</a></i>
parameter).</td>
</tr>
<tr nosave="" valign="top">
<td nosave="">&nbsp;&nbsp;&nbsp; 6</td>
<td>Trace information (enter/exit) for major Zoltan interface
routines
(printed by all processors).</td>
</tr>
<tr nosave="" valign="top">
<td nosave="">&nbsp;&nbsp;&nbsp; 7</td>
<td>More detailed trace information in major Zoltan interface
routines.</td>
</tr>
<tr nosave="" valign="top">
<td>&nbsp;&nbsp;&nbsp; 8</td>
<td nosave="">List of objects to be imported to and exported from
each processor.
&sup1;</td>
</tr>
<tr valign="top">
<td>&nbsp;&nbsp;&nbsp; 9</td>
<td><br>
</td>
</tr>
<tr valign="top">
<td>&nbsp;&nbsp; 10</td>
<td>Maximum debug output; may include algorithm-specific output.
&sup1;</td>
</tr>
<tr nosave="">
<td colspan="2" nosave="">&sup1; <i>Output may be serialized;
that is, one
processor may have to complete its output before the next processor is
allowed to begin its output.&nbsp; This serialization is not scalable
and
can significantly increase execution time on large number of processors.</i></td>
<td><br>
</td>
</tr>
</tbody>
</table>
</p>
<p></p>
<hr width="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a
href="ug_alg.html">Next:&nbsp;
Load-Balancing Algorithms</a>&nbsp; |&nbsp; <a href="ug_query_mig.html">Previous:&nbsp;
Migration Query Functions</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

161
thirdParty/Zoltan/docs/ug_html/ug_query.html vendored Normal file
View File

@ -0,0 +1,161 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Query Functions</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_query_lb.html">Next</a>&nbsp; |&nbsp; <a href="ug_interface_color.html">Previous</a></i></b></div>
<h2>
<a NAME="Application-Registered Query Functions"></a>Application-Registered
Query Functions</h2>
Zoltan gets information about a processor's objects
through calls to query functions. These functions
must be provided by the application. They are "registered" with Zoltan;
that is, a pointer to the function is passed to Zoltan,
which can then call that function when its information is needed.&nbsp;
<p>
Query functions return information about only on-processor data.
They can be called by Zoltan with individual objects
or lists of objects. Each processor may call a given query function
zero, one or
more than one time. Thus, most query functions should NOT contain
interprocessor communication, as such communication can cause
processors to hang while
waiting for messages that were never sent. (The only exceptions to this rule
are certain <a href="ug_query_mig.html">migration query functions</a>.)
<p>
Two categories of query functions are used by the library:
<blockquote><a href="ug_query_lb.html">General Zoltan Query Functions</a>
<br><a href="ug_query_mig.html">Migration Query Functions</a></blockquote>
In each category, a variety of query functions can be registered by the
user. The query functions have a function type, describing their
purpose.&nbsp; Functions can be registered with a
Zoltan structure in two ways:&nbsp; through calls to <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or through calls to query-function-specific functions <b><a href="ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</a></b>.&nbsp;
When a function is registered through a call to <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>,
its function type is passed in the <i>fn_type</i> argument. When <b><a href="ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</a></b>
is used to register functions, the type of the function is implicit in
the <i>fn_ptr</i> argument.&nbsp; Each function description below includes
both its function type and function prototype.
<p>
Query functions that return information about data objects owned by a processor
come in two forms: list-based functions that return information about a
list of objects, and iterator functions that return information about a single
object.
Users can provide either version of the query function; they need not provide
both.
Zoltan calls the list-based functions with the IDs of all objects needed;
this approach often provides faster performance as it eliminates the overhead
of multiple function calls. List-based functions have the word "MULTI" in
their function-type name. If, instead, the application provides iterator
functions, Zoltan calls the iterator function once for each object whose
data is needed. This approach, while slower, allows Zoltan to use less memory
for some data.
<p>
Some algorithms in Zoltan require that certain query
functions be registered by the application; for example, geometric partitioning
algorithms such as Recursive Coordinate Bisection (RCB) require that either a
<b><a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN</a></b> or a
<b><a href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b>
be registered. When a default value is specified below, the query function
type is optional; if a function of that type is not registered, the default
values are used. Details of which query functions are required by particular
algorithms are included in the <a href="ug_alg.html">Algorithms</a> section.
<p>
Many of the functions have both global and local object identifiers
(IDs) in their argument lists. The global IDs provided by the application
must be unique across all processors; they are used for identification
within Zoltan. The local IDs are not used by Zoltan;
they are provided for the convenience of the application and can
be anything the application desires. The local IDs can be used by application
query routines to enable direct access to application data. For example,
the object with global ID "3295" may be stored by the application in location
"15" of an array in the processor's local memory. Both global ID "3295"
and local ID "15" can be used by the application to describe the object.
Then, rather than searching the array for global ID "3295," the application
query routines can subsequently use the local ID to index directly into
the local storage array. See <a href="ug_usage.html#Data Types for Object IDs">Data
Types for Object IDs</a> for a description of global and local IDs. All
of the functions have, as their first argument, a pointer to data that
is passed to Zoltan through <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>
or <b><a href="ug_interface_init.html#Zoltan_Set_Specific_Fn">Zoltan_Set_&lt;<i>zoltan_fn_type</i>>_Fn</a></b>.&nbsp;
This data is not used by Zoltan. A different set of
data can be supplied for each registered function. For example, if the
local ID is an index into an array of data structures, then the data pointer
might point to the head of the data structure array.
<p>As their last argument, all functions have
an <a href="ug_interface.html#Error Codes">error code</a> that should
be set and returned by the registered function.
<p>
If you are calling the Zoltan library from a C++ application, you may
set the query function to be any class static function
or any function
defined outside of a class definition. However, it is possible you
will wish to set the query function to be an object method.
In that case, you should
write a query function that takes a pointer to the object as its
<I>data</I> field. The query function can then call the object
method.
<br>&nbsp;
<br>&nbsp;
<p>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_query_lb.html">Next:&nbsp;
Load-Balancing Query Functions</a>&nbsp; |&nbsp; <a href="ug_interface_color.html">Previous:&nbsp;
Coloring Functions</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

3729
thirdParty/Zoltan/docs/ug_html/ug_query_lb.html vendored Normal file
View File

File diff suppressed because it is too large Load Diff

1695
thirdParty/Zoltan/docs/ug_html/ug_query_mig.html vendored Normal file
View File

File diff suppressed because it is too large Load Diff

261
thirdParty/Zoltan/docs/ug_html/ug_refs.html vendored Normal file
View File

@ -0,0 +1,261 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: References</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_index.html">Next</a>&nbsp; |&nbsp; <a href="ug_backward.html">Previous</a></i></b></div>
<h2>
<a NAME="References"></a>References</h2>
<ol>
<li>
<a NAME="alegra"></a>"ALEGRA -- A Framework for Large Strain Rate Physics."
<a href="https://sherpa.sandia.gov/9231home/alegra/alegra-frame.html">https://sherpa.sandia.gov/9231home/alegra/alegra-frame.html</a></li>
<li>
<a NAME="attaway"></a>S. Attaway, T. Barragy, K. Brown, D. Gardner, B.
Hendrickson, S. Plimpton and C. Vaughan. "Transient Solid Dynamics Simulations
on the Sandia/Intel Teraflop Computer." <i>Proceedings of SC'97</i>, San
Jose, CA, November, 1997. (Finalist for the Gordon Bell Prize.)</li>
<a NAME="catalyurek99"></a>U. Catalyurek and C. Aykanat,
"Hypergraph-partitioning-based decomposition for parallel
sparse matrix vector multiplication", <i>IEEE Trans. Parallel Dist. Systems</i>,
v. 10, no. 7, (1999) pp. 673--693.
<li>
<a NAME="baehmann"></a>P. Baehmann, S. Wittchen, M. Shephard, K. Grice,
and M. Yerry. "Robust geometrically based automatic two-dimensional mesh
generation." <i>Intl. J. Numer. Meths. Engrg</i>., <i>24</i> (1987) 1043-1078.</li>
<li>
<a NAME="d1color"></a>E.G. Boman, D. Bozdag, U. Catalyurek,
A.H. Gebremedhin and F. Manne. "A Scalable Parallel Graph Coloring
Algorithm for Distributed Memory Computers". <i>Proceedings of Euro-Par'05</i>,
Lisbon, Portugal, August, 2005.</li>
<li>
<a NAME="d2color"></a>D. Bozdag, U. Catalyurek, A.H. Gebremedhin,
F. Manne, E.G. Boman and F. Ozguner. "A Parallel Distance-2 Graph
Coloring Algorithm for Distributed Memory Computers". <i>Proceedings of
HPCC'05</i>, Sorrento, Italy, September, 2005.</li>
<li>
<a NAME="berger"></a>M. Berger and S. Bokhari. "A partitioning strategy
for nonuniform problems on multiprocessors." <i>IEEE Trans. Computers</i>,
C-36 (1987) 570-580.</li>
<li>
<a NAME="culberson"></a>J. C. Culberson, “Iterated greedy graph
coloring and the difficulty landscape” <i>University of Alberta,
Tech. Rep. TR 92-07, Jun. 1992</i> </li>
<li>
<a NAME="hypergraph-ipdps06"></a>K.D. Devine, E.G. Boman, R. Heaphy,
R.H. Bisseling, U.V. Catalyurek. "Parallel Hypergraph Partitioning
for Scientific Computing", Proc. of IPDPS'06, Rhodos, Greece, April 2006.
</li>
<li>
<a NAME="mpsalsa-gordonbell"></a>K. Devine, G. Hennigan, S. Hutchinson,
A. Salinger, J. Shadid, and R. Tuminaro. "High Performance MP Unstructured
Finite Element Simulation of Chemically Reacting Flows." <i>Proceedings
of SC'97</i>, San Jose, CA, November, 1997. (Finalist for the Gordon Bell
Prize.)</li>
<li>
<A NAME="adapt03"></a>K.D. Devine, E.G. Boman, R.T. Heaphy, B.A. Hendrickson,
J.D. Teresco, J. Faik, J.E. Flaherty, and L.G. Gervasio. "New
challenges in dynamic load balancing." Williams College Department of
Computer Science Technical Report CS-04-02, and Sandia Report SAND2004-1496J, Sandia National Laboratories, 2004.
Submitted to <i>Applied Numerical Mathematics</i>.</LI>
<li>
<a NAME="edwards"></a>H.C. Edwards. <i>A parallel infrastructure for scalable
adaptive finite element methods and its application to least squares&nbsp;
C^(inf)</i> collocation.&nbsp; Ph.D. Dissertation, Univ. of Texas at Austin,
May, 1997.</li>
<li>
<A NAME="cluster04">J. Faik, J.E. Flaherty, L.G. Gervasio, J.D. Teresco, K,D.
Devine, and E.G. Boman.
"A model for resource-aware load balancing on heterogeneous clusters."
Williams College Department of Computer Science Technical Report CS-04-03,
and Sandia Report SAND2004-2145C, Sandia National Laboratories, 2004.
<I>Presented at Cluster '04.</I>
</LI>
<li>
<a NAME="flaherty"></a>J. Flaherty, R. Loy, M. Shephard, B. Szymanski,
J. Teresco and L. Ziantz. "Adaptive local refinement with octree load-balancing
for the parallel solution of three-dimensional conservation laws." <i>J.
Parallel Distrib. Comput.</i>, <i>47</i> (1998) 139-152.</li>
<li>
<a NAME="gervasio"></a>L. Gervasio. "Final Report." Summer project report,
Internal Memo, Department 9103, Sandia National Laboratories, August, 1998.</li>
<li>
<a NAME="hendrickson-devine"></a>B. Hendrickson and K. Devine. "Dynamic
load balancing in computational mechanics." <i>Comp. Meth. Appl. Mech.
Engrg.</i>, v. 184 (#2-4), p. 485-500, 2000.</li>
<li>
<a NAME="hendrickson-kolda"></a>B. Hendrickson and T.G. Kolda.
"Partitioning rectangular and structurally nonsymmetric sparse matrices for parallel computation", <i>SIAM J. on Sci. Comp.</i>, v. 21, no. 6, 2001, pp. 2048-2072.
<li>
<a NAME="chaco"></a>B. Hendrickson and R. Leland. "The Chaco user's guide,
version 2.0." Tech. Rep. SAND 94-2692, Sandia National Laboratories, Albuquerque,
NM, October, 1994. <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. "ParMETIS: Parallel graph
partitioning and sparse matrix ordering library." Tech. Rep. 97-060, Department
of Computer Science, Univ. of Minnesota, 1997. <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="loy"></a>R. Loy. <i>Adaptive local refinement with octree load-balancing
for the parallel solution of three-dimensional conservation laws</i>. Ph.
D. Dissertation, Dept. of Computer Science, Rensselaer Polytechnic Institute,
May 1998.</li>
<li>
<a NAME="mitchell"></a>S. Mitchell and S. Vavasis. "Quality mesh generation
in three dimensions." <i>Proc. 8th ACM Symposium on Computational Geometry</i>,
ACM (1992) 212-221.</li>
<li>
<a NAME="f90gl"></a>W. F. Mitchell. "A Fortran 90 Interface for OpenGL:
Revised January 1998" NISTIR 6134 (1998).
<a href="https://math.nist.gov/~mitchell/papers/nistir6134.ps.gz">https://math.nist.gov/~mitchell/papers/nistir6134.ps.gz</a></li>
<li>
<a NAME="reftree"></a>
W.F. Mitchell. "A Refinement-tree Based Partitioning Method for Dynamic Load
Balancing with Adaptively Refined Grids."
<i>Journal of Parallel and Distributed Computing</i>, Volume 67, Issue 4,
April 2007, Pages 417-429. </li>
<li>
<a NAME="mpsalsa"></a>"MPSalsa: Massively Parallel Numerical Methods for
Advanced Simulation of Chemically Reacting Flows." <a href="http://cs.sandia.gov/CRF/MPSalsa/">http://cs.sandia.gov/CRF/MPSalsa/</a></li>
<li>
<a NAME="patra"></a>A. Patra and J. T. Oden. "Problem decomposition for
adaptive hp-finite element methods." <i>J. Computing Systems in Engrg.</i>,
6 (1995).</li>
<li>
<a NAME="pilkington"></a>J. Pilkington and S. Baden. "Partitioning with
space-filling curves." Tech. Rep. CS94-349, Dept. of Computer Science and
Engineering, Univ. of California, San Diego, CA, 1994.</li>
<li>
<a NAME="sariyuce"></a>A. E. Sariyuce, E. Saule, U. V. Catalyurek. "Improving Graph
Coloring on Distributed Memory Parallel Computers" <i>Proceedings of the 18th Annual
International Conference on High Performance Computing (HiPC 2011)</i>, 2011, to appear.
</li>
<li>
<a NAME="shephard"></a>M. Shephard and M. Georges. "Automatic three-dimensional
mesh generation by the finite octree technique." <i>Intl. J. Numer. Meths.
Engrg.</i>, 32 (1991) 709-749.</li>
<li>
<a NAME="taylor"></a>V. E. Taylor and B. Nour-Omid. "A Study of the Factorization
Fill-in for a Parallel Implementation of the Finite Element Method." <i>Intl.
J. Numer. Meths. Engrg.</i>, 37 (1994) 3809-3823.</li>
<li>
<A NAME="cise-drum"></A>J. D. Teresco, J. Faik, and J. E. Flaherty. "Resource-Aware Scientific Computation on a Heterogeneous Cluster." <I>Computing in Science &amp; Engineering</I>, To appear, 2005.
</LI>
<li>
<A NAME="para04"></A>J. D. Teresco, J. Faik, and J. E. Flaherty.
"Hierarchical Partitioning and Dynamic Load Balancing for Scientific
Computation." Williams College Department of Computer Science
Technical Report CS-04-04, and Sandia Report SAND2004-1559A, Sandia
National Laboratories, 2004. Submitted to <i>Proc. PARA'04 Workshop on
State-Of-The-Art in Scientific Computing.</I>
</LI>
<li>
<a NAME="jostle"></a>C. Walshaw. "JOSTLE mesh partitioning software", <a href="https://www.gre.ac.uk/jostle/">https://www.gre.ac.uk/jostle/</a></li>
<li>
<a NAME="walshaw"></a>C. Walshaw, M. Cross, and M. Everett. "Parallel Dynamic
Graph Partitioning for Adaptive Unstructured Meshes", <i>J. Par. Dist.
Comp.</i>, 47(2) 102-108, 1997.</li>
<li>
<a NAME="warren"></a>M. Warren and J. Salmon. "A parallel hashed octree
n-body algorithm." <i>Proc. Supercomputing `93</i>, Portland, OR, November
1993.</li>
<li>
<a NAME="williams"></a>R. D. Williams. "Performance of dynamic load balancing algorithms for unstructured mesh calculations. <i>Concurrency, Practice, and Experience</i>, 3(5), 457-481, 1991.
</li>
</ol>
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_index.html">Next:&nbsp; Index of Interface and Query Functions</a>&nbsp; |&nbsp; <a href="ug_backward.html">Previous:&nbsp; Backward Compatibility</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

747
thirdParty/Zoltan/docs/ug_html/ug_release.html vendored Normal file
View File

@ -0,0 +1,747 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Release Notes</title>
</head>
<body bgcolor="#ffffff">
<div align="right"><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_backward.html">Next</a>&nbsp; |&nbsp; <a
href="ug_examples_query.html">Previous</a></i></b></div>
<!---------------------------------------------------------------------------->
<h2><a name="Release Notes">Release Notes
</a></h2>
<a name="Release Notes">Release notes are available for the following
releases of Zoltan:
</a>
<blockquote>
<a href="#Release3.83">Zoltan Release v3.83 in Trilinos v12.6</a><br>
<a href="#Release3.82">Zoltan Release v3.82 in Trilinos v12</a><br>
<a href="#Release3.81">Zoltan Release v3.81 in Trilinos v11.12</a><br>
<a href="#Release3.8">Zoltan Release v3.8 in Trilinos v11</a><br>
<a href="#Release3.7">Zoltan Release v3.7 in Trilinos v11</a><br>
<a href="#Release3.6">Zoltan Release v3.6</a><br>
<a href="#Release3.501">Zoltan Release v3.501</a><br>
<a href="#Release3.5">Zoltan Release v3.5</a><br>
<a href="#Release3.3">Zoltan Release v3.3</a><br>
<a href="#Release3.2">Zoltan Release v3.2</a><br>
<a href="#Release3.1">Zoltan Release v3.1</a><br>
<a href="#Release3.0">Zoltan Release v3.0</a><br>
<a href="#Release2.1">Zoltan Release v2.1</a><br>
<a href="#Release2.02">Zoltan Release v2.02</a><br>
<a href="#Release2.01">Zoltan Release v2.01</a><br>
<a href="#Release2.0">Zoltan Release v2.0</a><br>
<a href="#Release1.54">Zoltan Release v1.54</a> <br>
<a href="#Release1.53">Zoltan Release v1.53</a> <br>
<a href="#Release1.52">Zoltan Release v1.52</a> <br>
<a href="#Release1.5">Zoltan Release v1.5</a> <br>
<a href="#Release1.3">Zoltan Release v1.3</a>
</blockquote>
<hr>
<h2><a name="Release3.83">Zoltan Release v3.83 in Trilinos v12.6; January 2016</a></h2>
<ul>
<li> Autotools files updated to avoid deprecated perl features </li>
<li> Added Zoltan_Get_Fn interface to return pointers to registered callback
functions.</li>
<li> Several bug fixes in Fortran90 interface </li>
<li> Subtle rounding error fixed in PHG hypergraph partitioner </li>
<li> Minor changes to distributed data directory to track number of nodes
per processor; include file DD.h is now named zoltan_dd_const.h </li>
</ul>
<hr>
<h2><a name="Release3.82">Zoltan Release v3.82 in Trilinos v12; May 2015</a></h2>
<ul>
<li> Minor code clean-up to remove compiler warnings and handle error conditions.
<li> Enable "make -j" when building Zoltan's Fortran90 interface with autotools.
</ul>
<hr>
<h2><a name="Release3.81">Zoltan Release v3.81 in Trilinos v11.12; November 2014</a></h2>
<ul>
<li> Several improvements were made to Zoltan's interface to ParMETIS v4,
METIS v5, and Scotch v6.
<li> New statistics were added to the RCB and RIB algorithms' output.
<li> Checks for MPI_VERSION 1 or 2 were added where appropriate to handle
MPI interface changes.
<li> For non-MPI builds of Zoltan, a bug in the serial MPI stubs siMPI was
fixed; the bug occurred when many MPI_Datatypes were defined by the
algorithm (e.g., in deep recursion level of multilevel partitioning methods).
<li> Several minor bugs were fixed.
<li> No Zoltan interfaces were changed; Zoltan 3.81 is fully
backward-compatible with Zoltan 3.8.
</ul>
<hr>
<h2><a name="Release3.8">Zoltan Release Notes v3.8: October 2013</a></h2>
<ul>
<li> An improved hash function reduces execution time in partitioning,
particularly when parameter RETURN_LISTS=PARTS is used.
<li> Several bug fixes address overflow issues in cases where integers A and B
are valid integers, but A*B overflows an integer.
</ul>
<hr>
<h2><a name="Release3.7">Zoltan Release Notes v3.7: September 2012</a></h2>
<ul>
<li> The following features (deprecated in Trilinos v10.8) are no longer
supported in Trilinos v11.
<ul>
<li>Zoltan is now released under Trilinos' BSD license.
<li> Zoltan v1.1 interface (as described in Zoltan include file lbi_const.h):
users should upgrade their Zoltan interface and include file zoltan.h.
Instructions are at the <a href="../Zoltan_FAQ.html">Zoltan FAQ page</a>.
<li> Partitioning method OCTPART: use partitioning method HSFC for similar
partitions with faster partitioning time.
<li> Use of DRUM as a Zoltan TPL: architecture-aware methods will be included
in Zoltan2.
</ul>
<li> Improved memory usage in Zoltan Distributed Data Directories. Memory is
now managed in a single block, eliminating excessive calls to malloc and
improving the runtime performance of the data directories and the
hierarchical partitioning algorithms that use them.
<li> Hierarchical partitioning received several performance, interface and
testing improvements. In particular, an easier-to-use interface has been
added using simple parameters (HIER_ASSIST, PLATFORM_NAME, TOPOLOGY)
instead of callback functions; the callback function interface is still
supported. Also, hierarchical partitioning can now be used with only
geometric partitioners and callbacks, whereas before it required
graph-based callbacks as well.
<li> Reduced the memory usage of RCB and RIB when parameter KEEP_CUTS=0.
<li> Increased use of point-to-point communication (instead of MPI_Alltoall)
in communication package for better performance on large number of
processors.
<li> Compilation with gcc 4.7 is now supported.
<li> Using MurmurHash for better hashing.
<li> Zoltan supports PT-Scotch v5.1.12 and ParMETIS v4, as well as some older
versions of these TPLs.
<li> Zoltan's graph build has been streamlined; if possible, use the parameter
"GRAPH_BUILD_TYPE" == "FAST_NO_DUP" for faster graph builds.
</ul>
<hr>
<h2><a name="Release3.6">Zoltan Release Notes v3.6: September 13, 2011</a></h2>
<ul>
<li>
Added new recoloring capability to Zoltan coloring algorithms, providing
lower numbers of colors at small additional cost.
</li>
<li>
Updated Zoltan to allow use of third-party libraries ParMETIS versions 3.1 and 4.0 and Scotch versions up to 5.1.12.
</li>
<li>
Updated Zoltan's hierarchical partitioning for greater efficiency.
</li>
</ul>
<hr>
<h2><a name="Release3.501">Zoltan Release Notes v3.501: May 12, 2011</a></h2>
Fixed bug in autotools installation of Zoltan;
file Zoltan_config.h is now installed
in the specified include directory.
<hr>
<h2><a name="Release3.5">Zoltan Release Notes v3.5: March 24, 2011</a></h2>
Features:
<ul>
<li>
Fix in Fortran90 interface that causes compilation and run-time problems
with gcc 4.5 and later when compiler optimization is enabled.
</li>
<li>
Support for 64-bit builds of Zoltan, enabling operation on more than 2B objects.
See details for building in the <a href="ug_usage.html">Zoltan User's Guide</a>.
</li>
<li>
Faster graph builds for very specific input types. See parameter
<a href="ug_graph_build.html">GRAPH_BUILD_TYPE</a>.
</li>
</ul>
<hr>
<h2><a name="Release3.3">Zoltan Release Notes v3.3: July 31, 2010</a></h2>
Features:
<ul>
<li>
New <a href="ug_order_local_hsfc.html">local ordering method based on
space-filling curves</a> to improve
memory and cache locality within a processor.
</li>
<li>
Ability to call graph partitioning algorithms using hypergraph callback
functions; this capability is useful applications with, say, block-structured
matrix distributions (e.g., SuperLU), where all information about a matrix
row or column is not available on a single processor.
</li>
<li>
Improved execution time of parallel hypergraph partitioning.
</li>
</ul>
<hr>
<h2><a name="Release3.2">Zoltan Release Notes v3.2: September 24, 2009</a></h2>
Features:
<ul>
<li>
New <a href="ug_alg_ptscotch.html">interface</a>
to <a href="https://www.labri.fr/perso/pelegrin/scotch/">
Scotch and PT-Scotch</a> parallel graph partitioning
algorithms.
</li>
<li>
Simplified interface to graph <a href="ug_interface_order.html">ordering</a>
and <a href="ug_interface_color.html">coloring</a> algorithms
</li>
<li>
Automated symmetrization of graphs for graph partitioning, coloring
and ordering.
(See parameters GRAPH_SYMMETRIZE and GRAPH_SYM_WEIGHT in the
<a href="ug_alg_ptscotch.html">Scotch</a> and
<a href="ug_alg_parmetis.html">ParMETIS</a> graph packages.)
</li>
<li>
Improved function
<a href="ug_interface_lb.html#Zoltan_LB_Eval"><b>Zoltan_LB_Eval</b></a>
returns more information about a decomposition to users.
</li>
<li>
Improved examples showing Zoltan usage in C and C++
are included in <i>zoltan/example</i>.
</li>
<li>
Improved support for <a href="ug_usage.html#Autotools">builds under autotools</a>,
including builds of Zoltan's F90 interface.
</li>
<li>
New support for <a href="ug_usage.html#CMake">CMake builds</a>
and testing through Trilinos; builds of
Zoltan's F90 interface are included.
</li>
<li>
Improved integration into
<a href="https://trilinos.sandia.gov/packages/isorropia/">Isorropia</a>
partitioners for Trilinos' Epetra classes.
</li>
</ul>
Backward compatibility:
<ul>
<li>
Interfaces to
<a href="ug_interface_color.html">Zoltan_Color</a>,
<a href="ug_interface_order.html">Zoltan_Order</a> and
<a href="ug_interface_lb.html#Zoltan_LB_Eval">Zoltan_LB_Eval</a> have changed.
</li>
<li>
The Zoltan native build environment, while still distributed, will no
longer be supported. Users should use the
<a href="ug_usage.html#Building the Library">autotools or CMake</a> systems.
Builds of the Zoltan F90 interface are supported in both autotools and
CMake.
</li>
</ul>
<hr>
<h2><a name="Release3.1">Zoltan Release Notes v3.1: September 26, 2008</a></h2>
Zoltan v3.1 includes the following new features:
<ul>
<li>
Important new capabilities for Matrix ordering are included in Zoltan v3.1.
<ul>
<li>
A graph/matrix ordering interface to
<a href="ug_order_ptscotch.html">PT-Scotch</a>, a
high-quality graph ordering and partitioning library from the University of
Bordeaux, is now available.
<li>
Zoltan's new <a href="ug_interface_order.html">matrix
ordering interface</a>
returns ordering information such as permutations and
separators to the application.
</ul>
<li>
New <a href="ug_alg_phg.html">hypergraph partitioning</a>
options for inexpensively
<a href="ug_alg.html#LB_APPROACH">refining</a> partitions are
included and controlled simply by parameters
<a href="ug_alg.html#LB_APPROACH">LB_APPROACH</a> and
<a href="ug_alg_phg.html">PHG_MULTILEVEL</a>.
<li>
Robustness improvements have been made to Zoltan's parallel
<a href="ug_alg_hypergraph.html">hypergraph</a>
partitioner and repartitioner.
<li>
A new <a href="ug_usage.html#TrilinosAutotools">Autotools
build environment</a> is available.
The native Zoltan build environment is still
supported in this release.
<li>
<a href="ug_usage.html#TrilinosAutotools">Serial, non-MPI builds</a>
of Zoltan are enabled through the new Autotools build environment.
<li>
Zoltan is now a
<a href="https://trilinos.sandia.gov">Trilinos</a> package.
Integration with <a href="https://trilinos.sandia.gov">Trilinos</a>,
is now tighter and more seamless.
In particular, Zoltan is the default partitioner for the Trilinos package
<a href="https://trilinos.sandia.gov/packages/isorropia/">Isorropia</a>,
a matrix-based interface to Zoltan.
</ul>
<p>
Please see the <a href="ug_backward.html">backward compatibility</a> section
for a detailed description of changes that may affect current users.
<hr>
<h2><a name="Release3.0"></a>Zoltan Release Notes v3.0: May 1, 2007</h2>
Zoltan v3.0 includes major new features.
<ul>
<li> <a href="ug_alg_phg.html">Parallel Hypergraph Repartitioning</a> combining
the improved communication metric of <a href="ug_alg_hypergraph.html">hypergraph
partitioning</a> with a
<a href="http://cs.sandia.gov/Zoltan/papers/Catalyurek_IPDPS07.pdf">new model</a>
for representing an existing partition while
computing a new one. This work received the "Best Algorithms Paper Award" at
the <a href="https://www.ipdps.org"> 2007 IEEE International Parallel and
Distributed Processing Symposium</a>.
<li> <a href="http://cs.sandia.gov/Zoltan/papers/wiley_chapter.pdf">Hypergraph refinement</a> to quickly
improve the quality of an existing partition.
<li> Improved partition quality within the Zoltan
<a href="ug_alg_phg.html">parallel hypergraph partitioner</a>.
<li> <a href="ug_alg_phg.html">Parallel graph partitioning</a> using
Zoltan's parallel hypergraph partitioner.
<li> Hypergraph partitioning with <a href="ug_alg_hypergraph.html">fixed
vertices</a>
that allows application to assign or "fix" objects to a desired part
before partitioning.
<li> Improved <a href="ug_alg.html#REMAP">part remapping</a> to reduce data migration costs in all
partitioners.
<li> Hybrid <a href="ug_alg_hier.html">hierarchical partitioning</a> that allows
different partitioning algorithms to be applied within a hierarchy of
computers (e.g., partitioning across a cluster of shared-memory processors,
followed by partitioning within each shared-memory processor).
<li> A new scheme for more easily specifying partitioning
<a href="ug_alg.html#LB_METHOD">methods</a> and
<a href="ug_alg.html#LB_APPROACH">approaches</a>
within the hypergraph and graph partitioners.
<li> Very <a href="ug_alg_simple.html">simple partitioners</a> that serve as
testing tools and examples for usage.
</ul>
<p>
Please see the <a href="ug_backward.html">backward compatibility</a> section
for a detailed description of changes that may affect current users.
<hr>
<h2><a name="Release2.1"></a>Zoltan Release Notes v2.1: October 5, 2006</h2>
Zoltan v2.1 includes a significant bug fix for the hypergraph partitioner.
We strongly recommend that users upgrade to Zoltan v2.1.
<hr>
<h2><a name="Release2.02"></a>Zoltan Release Notes v2.02: September 26, 2006</h2>
Zoltan v2.02 includes bugfixes:
<ul>
<li>Zoltan_LB_Eval now correctly computes edge cuts with respect to parts
when parts are spread across more than one processor.
</li>
<li>Extraneous (and annoying) print statement has been removed from
Zoltan partitioning method RCB.
</li>
</ul>
<hr>
<h2><a name="Release2.01"></a>Zoltan Release Notes v2.01: August 2006</h2>
Zoltan v2.01 includes enhancements to version 2.0.
<ul>
<li>F90 interface fixes to comply with standard F90 (e.g., shortened
variable names and continuation lines). The hypergraph callback function
names have changed, but C and C++ compatibility with v2.0 is maintained.</li>
<li>Performance improvement to initial building of hypergraphs from
application data.</li>
<li>Major bug fix for dense-edge removal in parallel hypergraph method;
partitioning of hypergraphs with edges containing more than 25% of
the vertices was affected by this bug.</li>
<li>Minor fixes to parallel hypergraph code.</li>
</ul>
<hr>
<h2><a name="Release2.0"></a>Zoltan Release Notes v2.0: April 2006</h2>
Zoltan v2.0 includes several major additions:<br>
<ul>
<li><a href="ug_alg_phg.html">Parallel hypergraph partitioning</a>. </li>
<li><a href="ug_color.html">Parallel graph coloring</a>, both distance-1 and distance-2.</li>
<li><a href="ug_alg_rcb.html">Multicriteria geometric partitioning (RCB)</a>.</li>
<li><a href="ug_cpp.html">C++ interface</a>.
</ul>
<p></p>
<hr>
<h2><a name="Release1.54"></a>Zoltan Release Notes v1.54</h2>
Some versions of MPICH have a bug in MPI_Reduce_scatter; they can
report
errors with MPI_TYPE_INDEXED.
In Zoltan v1.54's unstructured communication package, calls to
MPI_Reduce_scatter have been replaced with separate calls to MPI_Reduce
and MPI_Scatter.
<p></p>
<hr>
<h2><a name="Release1.53"></a>Zoltan Release Notes v1.53</h2>
Zoltan v1.53 includes the following new capabilities:
<ul>
<li> Portability to BSD Unix and Mac OS X was added.
</li>
<li> Averaging of RCB and RIB cuts was added; see Zoltan parameter
<a href="ug_alg_rcb.html#AVERAGE_CUTS">AVERAGE_CUTS</a>.
</li>
<li> A new function <a href="ug_alg_rcb.html#Zoltan_RCB_Box"><b>Zoltan_RCB_Box</b></a>
returns information about subdomain bounding
boxes in RCB decompositions.
</li>
<li>
F90 interface to
<a href="ug_interface_order.html#Zoltan_Order"><b>Zoltan_Order</b></a>
was added.
</li>
<li>
Warnings that load-imbalance tolerance was not met are no longer
printed
when <a href="ug_param.html#Debug%20Levels%20in%20Zoltan">DEBUG_LEVEL</a>
== 0.
</li>
<li>
Minor bugs were addressed.
</li>
</ul>
<hr>
<h2><a name="Release1.52"></a>Zoltan Release Notes v1.52</h2>
Zoltan v1.52 includes the following new capabilities:
<ul>
<li>
List-based graph callback functions
<a href="ug_query_lb.html#ZOLTAN_NUM_EDGES_MULTI_FN">ZOLTAN_NUM_EDGES_MULTI_FN</a>
and <a href="ug_query_lb.html#ZOLTAN_EDGE_LIST_MULTI_FN">ZOLTAN_EDGE_LIST_MULTI_FN</a>
were added to mirror support and performance given by the
list-based geometric function <a
href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a>.
</li>
<li>
Support for ParMETIS v3.1 was added. </li>
<li>
Minor bugs were addressed.
</li>
</ul>
<hr>
<h2><a name="Release1.5"></a>Zoltan Release Notes v1.5</h2>
This section describes improvements to Zoltan in Version 1.5.
Every attempt was made to keep Zoltan v1.3 backwardly compatible with
previous versions.
Users of previous versions of Zoltan should refer to the <a
href="ug_backward.html">Backward Compatibility Notes</a>.
<p>Short descriptions of the following features are included below;
follow the links for more details.
</p>
<blockquote><a href="#REMAP">Part remapping</a>
<br>
<a href="#KNEP">Unequal Numbers of Parts and Processors</a>
<br>
<a href="#UnequalSizes">Non-Uniform Part Sizes</a>
<br>
<a href="#Interface1.5">Zoltan Interface Updated</a>
<br>
<a href="#HSFCBox">Robust HSFC Box Assign</a>
<br>
<a href="#Matrix">Matrix Ordering</a>
<br>
<a href="#Performance1.5">Performance Improvements</a>
<br>
<a href="#BugFixes1.5">Bug Fixes</a>
</blockquote>
<!---------------------------------------------------------------------------->
<h4><a name="REMAP"></a>
<hr>Part Remapping</h4>
During partitioning, Zoltan v1.5 can renumber parts so that the
input and output partitions have greater overlap (and, thus, lower
data-migration costs). This remapping is controlled by Zoltan parameter
<i><a href="ug_alg.html#REMAP">REMAP</a></i>. Experiments have shown
that
using this parameter can greatly reduce data migration costs.
<!---------------------------------------------------------------------------->
<h4><a name="KNEP"></a>
<hr>Unequal Numbers of Parts and Processors</h4>
Zoltan v1.5 can be used to generate <i>k</i> parts on <i>p</i>
processors,
where <i>k</i> is not equal to <i>p</i>. Function <a
href="ug_interface_lb.html#Zoltan_LB_Partition"><b>Zoltan_LB_Partition</b></a>
(replacing <a href="ug_interface_lb.html#Zoltan_LB_Balance"><b>Zoltan_LB_Balance</b></a>)
can generate arbitrary numbers of parts on the given processors.
The number of desired parts is set with parameters <i><a
href="ug_alg.html#NUM_GLOBAL_PARTS">NUM_GLOBAL_PARTS</a></i>
or <i><a href="ug_alg.html#NUM_LOCAL_PARTS">NUM_LOCAL_PARTS</a></i>.
Both part and processor information are returned by
<a href="ug_interface_lb.html#Zoltan_LB_Partition"><b>Zoltan_LB_Partition</b></a>,
<b><a href="ug_interface_augment.html#Zoltan_LB_Box_PP_Assign">Zoltan_LB_Box_PP_Assign</a></b>,
and
<b><a href="ug_interface_augment.html#Zoltan_LB_Point_PP_Assign">Zoltan_LB_Point_PP_Assign</a></b>.
New Zoltan query functions
<b><a href="ug_query_lb.html#ZOLTAN_PART_FN">ZOLTAN_PART_FN</a></b>
and <b><a href="ug_query_lb.html#ZOLTAN_PART_MULTI_FN">ZOLTAN_PART_MULTI_FN</a></b>
return objects' part information to Zoltan.
<a href="ug_interface_lb.html#Zoltan_LB_Balance"><b>Zoltan_LB_Balance</b></a>
can still be used for <i>k</i> equal to <i>p</i>.
<!---------------------------------------------------------------------------->
<h4><a name="UnequalSizes"></a>
<hr>Non-Uniform Part Sizes</h4>
Part sizes for local and global parts can be specified using
<b><a href="ug_interface_lb.html#Zoltan_LB_Set_Part_Sizes">Zoltan_LB_Set_Part_Sizes</a></b>,
allowing non-uniformly sized parts to be generated by
Zoltan's partitioning algorithms.
<!---------------------------------------------------------------------------->
<h4><a name="Interface1.5"></a>
<hr>Zoltan Interface Updated</h4>
To support the concept of parts separate from processors, many new
interface functions were added to Zoltan v1.5 (e.g.,
<a href="ug_interface_lb.html#Zoltan_LB_Partition"><b>Zoltan_LB_Partition</b></a>
and
<b><a href="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>).
These functions mimic previous Zoltan functions (e.g.,
<a href="ug_interface_lb.html#Zoltan_LB_Balance"><b>Zoltan_LB_Balance</b></a>
and
<b><a href="ug_interface_mig.html#Zoltan_Help_Migrate">Zoltan_Help_Migrate</a></b>,
respectively), but include both part and processor information.
Both the new and old interface functions work in Zoltan v1.5.
See the notes on <a href="ug_backward.html">Backward Compatibility</a>.
<!---------------------------------------------------------------------------->
<h4><a name="HSFCBox"></a>
<hr>Robust HSFC Box Assign</h4>
Function
<b><a href="ug_interface_augment.html#Zoltan_LB_Box_PP_Assign">Zoltan_LB_Box_PP_Assign</a></b>
now works for the <a href="ug_alg_hsfc.html">Hilbert Space-Filling
Curve algorithm (HSFC)</a>,
in addition to the <a href="ug_alg_rcb.html">RCB</a> and <a
href="ug_alg_rib.html">RIB</a> algorithms supported in previous
versions
of Zoltan. <b><a
href="ug_interface_augment.html#Zoltan_LB_Point_PP_Assign">Zoltan_LB_Point_PP_Assign</a></b>
continues to work for <a href="ug_alg_hsfc.html">HSFC</a>,
<a href="ug_alg_rcb.html">RCB</a> and <a href="ug_alg_rib.html">RIB</a>.
<!---------------------------------------------------------------------------->
<h4><a name="Matrix"></a>
<hr>Matrix Ordering</h4>
Zoltan v1.5 contains a matrix-ordering interface <b><a
href="ug_interface_order.html#Zoltan_Order">Zoltan_Order</a></b>
to ParMETIS' matrix-ordering
functions. New graph-based matrix-ordering algorithms can be easily
added behind this interface.
<!---------------------------------------------------------------------------->
<h4><a name="Performance1.5"></a>
<hr>Performance Improvements</h4>
Many performance improvements were added to Zoltan v1.5.
<ul>
<li>
List-based callback functions have been added to Zoltan
(<b><a href="ug_query_lb.html#ZOLTAN_GEOM_MULTI_FN">ZOLTAN_GEOM_MULTI_FN</a></b>,
<b><a href="ug_query_lb.html#ZOLTAN_PART_MULTI_FN">ZOLTAN_PART_MULTI_FN</a></b>,
<b><a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_MULTI_FN">ZOLTAN_OBJ_SIZE_MULTI_FN</a></b>,
<b><a href="ug_query_mig.html#ZOLTAN_PACK_OBJ_MULTI_FN">ZOLTAN_PACK_OBJ_MULTI_FN</a></b>,
and
<b><a href="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_MULTI_FN">ZOLTAN_UNPACK_OBJ_MULTI_FN</a></b>);
these functions allow entire lists of data to be passed from the
application to Zoltan, replacing per-object callbacks.
</li>
<li>
<b><a href="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>
now
can accept either import lists, export lists, or both. It is no longer
necessary to call <b><a
href="ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a></b>
or <b><a href="ug_interface_mig.html#Zoltan_Compute_Destinations">Zoltan_Compute_Destinations</a></b>
to get appropriate input for <b><a
href="ug_interface_mig.html#Zoltan_Migrate">Zoltan_Migrate</a></b>.
</li>
<li>
Zoltan v1.5 contains performance improvements within individual
algorithms.
We recommend users upgrade to the latest version.
</li>
</ul>
<!---------------------------------------------------------------------------->
<a name="BugFixes1.5"></a>
<hr>
<h4>Bug Fixes</h4>
Bug fixes were made to Zoltan's algorithms and interface. Users
of previous versions of Zoltan are encouraged to upgrade.
<!----------------------------------------------------------------------------><!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<hr>
<h2><a name="Release1.3"></a>Zoltan Release Notes v1.3</h2>
This section describes improvements to Zoltan in Version 1.3.
Every attempt was made to keep Zoltan v1.3 backwardly compatible with
previous versions.
Users of previous versions of Zoltan should refer to the <a
href="ug_backward.html">Backward Compatibility Notes</a>.
<p>Short descriptions of the following features are included below;
follow the links for more details.
</p>
<blockquote><a href="#Data%20Services">More Data Services</a>
<br>
<a href="#New%20HSFC">New Hilbert Space-Filling Curve Partitioning</a>
<br>
<a href="#New%20Structured">Support for Structured-Grid Partitioning</a>
<br>
<a href="#ParMETIS3">Support for ParMETIS v3.0</a>
<br>
<a href="#Performance">Performance Improvements</a>
<br>
<a href="#New%20Interface">Zoltan Interface Updated</a>
<br>
<a href="#TestSuite">Improved Test Suite</a>
<br>
<a href="#BugFixes">Bug Fixes</a>
</blockquote>
<!---------------------------------------------------------------------------->
<a name="Data Services"></a>
<hr>
<h4>More Data Services</h4>
Zoltan's mission has been widened beyond its original focus on dynamic
load-balancing algorithms. Now Zoltan also provides data management
services to parallel, unstructured, and adaptive computations.
Several packages of parallel data services have been added and made
available to
application developers. These services include the following:
<ul>
<li>An <a href="ug_util_comm.html">unstructured
communication package</a> that simplifies complicated communication by
insulating applications from the details of message
sends and receives.
</li>
<li>A <a href="ug_util_dd.html">distributed data directory</a>
that allows applications to efficiently
(in memory and time) locate off-processor data.
</li>
<li>A <a href="ug_util_mem.html">dynamic memory
management package</a> that simplifies debugging of
memory allocation problems on state-of-the-art parallel computers.
</li>
</ul>
<!---------------------------------------------------------------------------->
<a name="New HSFC"></a>
<hr>
<h4>New Hilbert Space-Filling Curve Partitioning</h4>
Zoltan now includes a fast, efficient implementation of <a
href="ug_alg_hsfc.html">Hilbert Space-Filling Curve (HSFC)</a>
partitioning. This geometric method also includes
support for <a href="ug_interface_augment.html#Zoltan_LB_Box_Assign">Zoltan_LB_Box_Assign</a>
and <a href="ug_interface_augment.html#Zoltan_LB_Point_Assign">Zoltan_LB_Point_Assign</a>
functions.<!----------------------------------------------------------------------------> <a
name="New Structured"></a>
<hr>
<h4>Support for Structured-Grid Partitioning</h4>
Zoltan's <a href="ug_alg_rcb.html">Recursive Coordinate Bisection (RCB)</a>
partitioning algorithm has been enhanced to allow
generation of strictly rectilinear subdomains. This capability can be
used for partitioning of grids for structured-grid applications. See
parameter <a href="ug_alg_rcb.html"><i>RCB_RECTILINEAR_BLOCKS</i></a>.
<!----------------------------------------------------------------------------><a
name="ParMETIS3"></a>
<hr>
<h4>Support for ParMETIS v3.0</h4>
In addition to providing interfaces to <a href="ug_alg_parmetis.html">ParMETIS
v2.0</a>,
Zoltan now provides an interfaces <a href="ug_alg_parmetis.html">ParMETIS
v3.0</a>. Full support of ParMETIS v3.0's multiconstraint and
multiobjective partitioning is
included.
<!----------------------------------------------------------------------------><a
name="Performance"></a>
<hr>
<h4>Performance Improvements</h4>
Performance of Zoltan's partitioning algorithms has been improved
through a number of code optimizations and new features. In addition,
user parameter <a href="ug_alg.html#LB%20Parameters"><i>RETURN_LISTS</i></a>
can be used to specify which returned arguments are computed by <a
href="ug_interface_lb.html#Zoltan_LB_Balance"><b>Zoltan_LB_Balance</b></a>,
allowing reduced work in partitioning.
In the <a href="ug_alg_rcb.html">Recursive Coordinate Bisection (RCB)</a>
partitioning algorithm, user parameters allow cut directions
to be locked in an attempt to minimize data movement; see parameters
<a href="ug_alg_rcb.html"><i>RCB_LOCK_DIRECTIONS</i></a> and <a
href="ug_alg_rcb.html"><i>RCB_SET_DIRECTIONS</i></a>.
<!----------------------------------------------------------------------------><a
name="New Interface"></a>
<hr>
<h4>Zoltan Interface Updated</h4>
Zoltan has adopted a more modular design, making it easier to use by
applications and easier to modify by algorithm developers.
Names in the <a href="ug_interface.html">Zoltan interface</a> and code
are tied more closely to their functionality.
Full <a href="ug_backward.html">backward compatibility</a> is
supported
for users of previous versions of Zoltan.
<!----------------------------------------------------------------------------><a
name="TestSuite"></a>
<hr>
<h4>Improved Test Suite</h4>
The Zoltan <a href="../dev_html/dev_test_script.html">test suite</a>
has been improved, with more tests providing greater
code coverage and platform-specific answer files accounting for
differences
due to computer architectures.
<!----------------------------------------------------------------------------><a
name="BugFixes"></a>
<hr>
<h4>Bug Fixes</h4>
Some bug fixes were made to Zoltan's algorithms and interface. Users
of previous versions of Zoltan are encouraged to upgrade.
<!---------------------------------------------------------------------------->
<p></p>
<hr width="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a
href="ug_backward.html">Next:&nbsp;
Backward Compatibility</a>&nbsp; |&nbsp; <a href="ug_examples_query.html">Previous:&nbsp;
Query Function Examples</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

444
thirdParty/Zoltan/docs/ug_html/ug_usage.html vendored Normal file
View File

@ -0,0 +1,444 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title>Zoltan User's Guide: Library Usage</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_cpp.html">Next</a>&nbsp; |&nbsp; <a href="ug_intro.html">Previous</a></i></b></div>
<h2>
<a NAME="Using the Library"></a>Using the Zoltan library</h2>
This section contains information needed to use the Zoltan library with
applications:
<blockquote>
<a href="#System Requirements">System requirements</a>
<br><a href="#Building the Library">Building the Zoltan library</a>
<br><a href="#Testing the Library">Testing the Zoltan library</a>
<br><a href="#ReportingBugs">Reporting bugs</a> in Zoltan
<br><a href="#Incorporating Zoltan">Incorporating Zoltan into Applications</a>
<br><a href="#Building Applications">Building applications</a>
that use Zoltan
<br><a href="#Data Types for Object IDs">Data types</a> for global and
local IDs
<br><a href="ug_cpp.html">C++ interface</a>
<br><a href="ug_fortran.html">F90 interface</a>
</blockquote>
<hr>
<h3>
<a NAME="System Requirements"></a>System Requirements</h3>
Zoltan was designed to run on parallel computers and clusters of workstations.
The most common builds and installations of Zoltan use the following:
<ul>
<li>
ANSI C or C++ compiler.</li>
<li>
<a href="https://www-unix.mcs.anl.gov/mpi/">MPI</a> library for message
passing (version 1.1 or higher), such as MPICH, OpenMPI or LAM.</li>
<li>
A Unix-like operating system (e.g., Linux or Mac OS X) and
<i>gmake</i> (GNU Make) are recommended to build the library.</li>
<li>
A Fortran90 compatible compiler is required if you wish to
<a href="ug_fortran.html">use Zoltan
with Fortran applications</a>.</li>
</ul>
Zoltan has been tested on a variety of platforms, including Linux, Mac OS X,
a variety of clusters, and Sandia's ASC RedStorm</a> machine.
Builds for Windows platforms are available as part of the
<a href=#CMake>Trilinos CMake build system</a>.
<hr>
<h3>
<a NAME="Building the Library"></a>Building the Zoltan Library</h3>
The Zoltan library is implemented in ANSI C and can be compiled with any
ANSI C compiler.
In Zoltan, there are two build environments currently supported:
an <a href="#Autotools">Autotools build environment</a>
and a <a href=#CMake">CMake build environment</a>
used with the <a href="https://trilinos.sandia.gov">Trilinos</a>
framework.
The Autotools build environment can be used to build Zoltan in a stand-alone
installation; the CMake build environment must be used within Trilinos.
<p>
<h4><a NAME="Autotools"></a>Using Autotools to Build Zoltan</h4>
Users should not run autotools directly in the main Zoltan directory;
rather they should create a build-directory (e.g., a subdirectory of
the main Zoltan directory) in which they configure and build Zoltan.
Say, for example, a user creates a directory called BUILD_DIR in the
Zoltan directory. Then, to configure and build zoltan, the user would
<blockquote>
cd zoltan/BUILD_DIR <br>
../configure {options described below} <br>
make everything <br>
make install <br>
</blockquote>
Options to the configure command allow paths
to third-party libraries such as ParMETIS, PT-Scotch and PaToH to be specified.
Building with MPI compilers (e.g., mpicc) is the default for Autotools builds
of Zoltan; many options allow specification of particular MPI paths and
compilers.
<p>
Users desiring a <a href="ug_fortran.html">Fortran90 interface</a>
to Zoltan must
specify the "--enable-f90interface" option.
<p>
All options can be seen
with the following command issued in the zoltan/BUILD_DIR directory:
<blockquote>
../configure --help
</blockquote>
<p>
The following script is an example of configuration and build commands
using Autotools. It specifies that Zoltan should be built with both
the <a href="ug_alg_parmetis.html">ParMETIS</a> and
<a href="ug_alg_ptscotch.html">PT-Scotch</a> interfaces.
Paths to both ParMETIS and PT-Scotch are given.
The prefix option states where Zoltan should be installed;
in this example, Zoltan's include files will be installed in
/homes/username/zoltan/BUILD_DIR/include, and the libraries
will be installed in /homes/username/zoltan/BUILD_DIR/lib.
This examples assumes the script is run from
/homes/username/zoltan/BUILD_DIR.
<blockquote>
#<br>
../configure \<br>
--prefix=/homes/username/zoltan/BUILD_DIR \<br>
--with-gnumake \<br>
--with-scotch \<br>
--with-scotch-incdir="/Net/local/proj/zoltan/arch/all/src/Scotch5" \<br>
--with-scotch-libdir="/Net/local/proj/zoltan/arch/linux64/lib/openmpi/Scotch5" \<br>
--with-parmetis \<br>
--with-parmetis-incdir="/Net/local/proj/zoltan/arch/all/src/ParMETIS3" \<br>
--with-parmetis-libdir="/Net/local/proj/zoltan/arch/linux64/lib/openmpi/ParMETIS3" <br>
make everything <br>
make install
</blockquote>
<p>
The configure script also allows you to specify the data type for a
global identifier. The choices are
unsigned int, unsigned long, and unsigned long long.
The default data type is unsigned int. If your
space of global identifiers requires more than 32 bits, you can specify a 64-bit data type.
<p>
<blockquote>
--with-id-type=uint<br>
--with-id-type=ulong<br>
--with-id-type=ullong<br>
</blockquote>
<p>
Support of 64-bit identifiers is new as of Zoltan version 3.5.
At this point in time all methods except for
<a href="ug_alg_reftree.html">refinement tree partitioning</a>
have been modified to work with 64-bit identifiers. Zoltan's
Fortran90 interface does not yet support 64-bit identifiers.
<p>
More examples are in the directory zoltan/SampleConfigurationScripts.
<p>
After the configuration is done in
the build directory, object files and executables can be removed with
<i>make clean</i>; the same configuration will be used for subsequent builds.
Configuration information is removed with <i>make distclean</i>.
<p>
<h4><a NAME="CMake"></a>Using CMake to Build Zoltan</h4>
Zoltan can be built as part of the Trilinos framework using the
CMake build system. CMake builds will succeed only when Zoltan is
in the Trilinos directory structure (as when downloaded with Trilinos).
Users should not run CMake directly in the main Zoltan directory;
rather they should create a build-directory (e.g., a subdirectory of
the main Trilinos directory) in which they configure and build Zoltan.
Say, for example, a user creates a directory called BUILD_DIR in the
Trilinos directory. Then, to configure and build zoltan, the user would
<blockquote>
cd Trilinos/BUILD_DIR <br>
cmake \ <br>
-D Trilinos_ENABLE_ALL_PACKAGES:BOOL=OFF \ <br>
-D Trilinos_ENABLE_Zoltan:BOOL=ON \ <br>
{options described below} \ <br>
.. <br>
make <br>
make install <br>
</blockquote>
<p>
CMake also allows you to specify the data type for a
global identifier. The choices are
unsigned int, unsigned long, and unsigned long long.
The default data type for a global identifier is unsigned int. The options to set the global identifier
data type are shown below.
<p>
<blockquote>
-D Zoltan_ENABLE_UINT_IDS:Bool=ON<br>
-D Zoltan_ENABLE_ULONG_IDS:Bool=ON<br>
-D Zoltan_ENABLE_ULLONG_IDS:Bool=ON<br>
</blockquote>
<p>
Support of 64-bit identifiers is new as of Zoltan version 3.5.
At this point in time all methods except for
<a href="ug_alg_reftree.html">refinement tree partitioning</a>
have been modified to work with 64-bit identifiers. Zoltan's Fortran90
interface does not yet support 64-bit identifiers.
<p>
<b>Serial</b> builds are the default in Trilinos; for serial builds, Zoltan
builds and links with the siMPI library provided by Pat Miller in the Zoltan
distribution. More commonly, Zoltan users desire <b>parallel</b> builds with
MPI libraries such as OpenMPI or MPICH. For such builds, users must specify
CMake option
<blockquote>
-D TPL_ENABLE_MPI:BOOL=ON
</blockquote>
Trilinos also defaults to using a Fortran compiler, but Fortran is not
required to build Zoltan; the option to disable this check is<br>
-D Trilinos_ENABLE_Fortran:BOOL=OFF
<p>
Other options to the cmake command allow paths
to third-party libraries such as ParMETIS, PT-Scotch and PaToH to be specified.
<p>
Users desiring a <a href="ug_fortran.html">Fortran90 interface</a>
to Zoltan must
specify the option<br>
-D Zoltan_ENABLE_F90INTERFACE:BOOL=ON<br>
<p>
All options can be seen
with the following command issued in the Trilinos/BUILD_DIR directory:
<blockquote>
rm CMakeCache.txt<br>
cmake -LAH -D Trilinos_ENABLE_Zoltan:BOOL=ON ..
</blockquote>
<p>
The following script is an example of configuration and build commands
using CMake. It specifies that Zoltan should be built with both
the <a href="ug_alg_parmetis.html">ParMETIS</a> and
<a href="ug_alg_ptscotch.html">PT-Scotch</a> interfaces.
Paths to both ParMETIS and PT-Scotch are given.
The prefix option states where Zoltan should be installed;
in this example, Zoltan's include files will be installed in
/homes/username/Trilinos/BUILD_DIR/include, and the libraries
will be installed in /homes/username/Trilinos/BUILD_DIR/lib.
This examples assumes the script is run from
/homes/username/Trilinos/BUILD_DIR.
<blockquote>
#<br>
cmake \ <br>
-D CMAKE_INSTALL_PREFIX:FILEPATH="/home/username/Trilinos/BUILD_DIR" \ <br>
-D TPL_ENABLE_MPI:BOOL=ON \ <br>
-D CMAKE_C_FLAGS:STRING="-m64 -g" \ <br>
-D CMAKE_CXX_FLAGS:STRING="-m64 -g" \ <br>
-D CMAKE_Fortran_FLAGS:STRING="-m64 -g" \ <br>
-D Trilinos_ENABLE_ALL_PACKAGES:BOOL=OFF \ <br>
-D Trilinos_ENABLE_Zoltan:BOOL=ON \ <br>
-D Zoltan_ENABLE_EXAMPLES:BOOL=ON \ <br>
-D Zoltan_ENABLE_TESTS:BOOL=ON \ <br>
-D Zoltan_ENABLE_ParMETIS:BOOL=ON \ <br>
-D ParMETIS_INCLUDE_DIRS:FILEPATH="/home/username/code/ParMETIS3_1" \ <br>
-D ParMETIS_LIBRARY_DIRS:FILEPATH="/home/username/code/ParMETIS3_1" \ <br>
-D Zoltan_ENABLE_Scotch:BOOL=ON \ <br>
-D Scotch_INCLUDE_DIRS:FILEPATH="/home/username/code/scotch_5.1/include" \ <br>
-D Scotch_LIBRARY_DIRS:FILEPATH="/home/username/code/scotch_5.1/lib" \ <br>
.. <br>
make <br>
make install
</blockquote>
<p>
More examples are in the directory zoltan/SampleCmakeScripts.
More details of CMake use in Trilinos are
in <br>
Trilinos/cmake/TrilinosCMakeQuickstart.txt.
<hr>
<h3>
<a NAME="Testing the Library"></a>Testing the Zoltan Library</h3>
The <I>examples</I> directory contains simple C and C++ examples which use
the Zoltan library. The makefile in this directory has three targets:
These examples are built automatically when the
<a href="#Autotools">Autotools build environment</a> or
<a href="#CMake">CMake build environment</a> is used.
<p>
The "right" answer for these tests depends on the number of processes with
which you run the tests. In general, if they compile successfully,
run quickly (in seconds), and produce reasonable looking output, then
Zoltan is built successfully.
<hr>
<h3>
<a NAME="ReportingBugs"></a>Reporting Bugs in Zoltan</h3>
Zoltan uses <a href="https://www.bugzilla.org">Bugzilla</a> to collect
bug reports. Please read the <a href="../Zoltan_bugreport.html">instructions for reporting bugs</a> through the Zoltan Bugzilla database.
<p>
<hr>
<h3>
<a NAME="Incorporating Zoltan"></a>Incorporating Zoltan into Applications</h3>
Incorporating Zoltan into applications requires three basic steps:
<ul>
<li>
Writing <a href="ug_query.html">query functions</a>
that return information about the application to Zoltan.
<li>
<a href="ug_interface_init.html">Initializing</a> Zoltan, <a href="ug_interface_init.html#Zoltan_Create">creating a
Zoltan object</a>, and
<a href="ug_interface_init.html#Zoltan_Set_Param">setting
appropriate parameters</a>.
<li>
Calling Zoltan tools to perform <a href="ug_interface_lb.html">partitioning</a>, <a href="ug_interface_order.html">ordering</a>, <a href="ug_interface_mig.html">migration</a>, <a href="ug_interface_color.html">coloring</a>, etc.
</ul>
The set of <a href="ug_query.html">query functions</a>
needed by an application depends on the
particular tools (e.g., <a href="ug_interface_lb.html">partitioning</a>,
<a href="ug_interface_order.html">ordering</a>) used and on
the <a href="ug_alg.html">algorithms</a>
selected within the tools. Not all query functions are needed by
every application. See documentation on tools and algorithms to determine
which query functions are needed.
<hr>
<h3>
<a NAME="Building Applications"></a>Building Applications that use Zoltan</h3>
The C library interface is described in the include file <i>include/zoltan.h</i>;
this file should be included in all C application source files that call
Zoltan library routines.
<p>
The <a href="ug_cpp.html">C++ interface</a> to
Zoltan is implemented in header files which define classes that
wrap the Zoltan C library. The file <I>include/zoltan_cpp.h</I> defines the
<B>Zoltan</B> class which encapsulates a load balancing data structure and the
Zoltan load balancing functions which operate upon it. Include this header file
instead in your C++ application. Note that C++ applications should call the
C function <B><a href="ug_interface_init.html#Zoltan_Initialize">Zoltan_Initialize</a></B> before creating a <B>Zoltan</B> object.
<p>
<a href="ug_fortran_apps.html">Fortran applications</a> must USE
<a href="ug_fortran_api.html#fortran ug api zoltan module">module zoltan</a> and
specify the Zoltan installation's <i>include</i> directory
as a directory to be searched for module information files.
<p>
The C, C++ or Fortran application should then be linked with the Zoltan library
(built with Fortran support in the Fortran case) by including
<blockquote><i>-lzoltan </i></blockquote>
in the linking command for the application.
Communication within
Zoltan is performed through MPI, so appropriate MPI libraries must be linked
with the application. Third-party libraries, such as <a href="ug_alg_parmetis.html">ParMETIS</a>, <a href="ug_alg_ptscotch.html">PT-Scotch</a>
and <a href="ug_alg_patoh.html">PaToH</a>, must be also be
linked with the application if they were included in compilation of the
Zoltan library.&nbsp;
<p>
The installed files <i>include/Makefile.export.zoltan*</i> contain macros that
can specify Zoltan paths and libraries in an application's Makefiles.
Using these files, applications can be assured they are using the same
build options that were used when Zoltan was built.
<hr>
<h3>
<a NAME="Data Types for Object IDs"></a>Data Types for Object IDs</h3>
Application query functions and application callable library functions
use global and local identifiers (IDs) for objects. <i>All objects to be
used in load balancing must have unique global IDs.</i> Zoltan stores an
ID as an array of ZOLTAN_ID_TYPE. The default for ZOLTAN_ID_TYPE is unsigned
int, but configuration parameters can select unsigned long or unsigned long long
as the type; see above for the appropriate configuration flags for
<a href="#Autotools">Autotools</a> and <a href="#CMake">CMake</a>.
The number of entries in these arrays
can be set using the <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a> parameters;
by default, one ZOLTAN_ID_TYPE represents an ID. Applications may use
whatever format is most convenient to store their IDs; the IDs can then
be converted to and from Zoltan's ID format in the <a href="ug_query.html">application-registered
query functions</a>.
<p>
Definitions of ZOLTAN_ID_TYPE and ZOLTAN_ID_MPI_TYPE
are in <i>include/zoltan_types.h</i>; they can
be used by an application for memory allocation, MPI communication, and
as arguments to
<a href="ug_interface.html">load-balancing interface functions</a>
and
<a href="ug_query.html">application-registered query functions</a>.
In the Fortran interface, IDs are passed as arrays of integers since unsigned
integers are not supported in Fortran. See the description of the <a href="ug_fortran_api.html#fortran ug api IDs">Fortran
interface</a> for more details.
<p>The local IDs passed to Zoltan are not used by the library; they are
provided for the convenience of the application and can contain any information
desired by the application. For instance, local array indices for objects
may be passed as local IDs, enabling direct access to object data in the
query function routines. See the <a href="ug_query.html">application-registered
query functions</a> for more details. The source code distribution contains
an example application <i><a href="../dev_html/dev_driver.html">zdrive</a></i>
in which global IDs are integers and local IDs are local array indices.
One may choose not to use local ids at all, in which case <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>
may be set to zero.
<p>Some Zoltan routines (e.g.,
<a href="ug_interface_lb.html#Zoltan_LB_Partition"><b>Zoltan_LB_Partition</b></a>
and
<a href="ug_interface_mig.html#Zoltan_Invert_Lists"><b>Zoltan_Invert_Lists</b></a>)
allocate arrays of type <b>ZOLTAN_ID_PTR</b> and return them to the application.
Others (e.g., <b><a href="ug_interface_order.html#Zoltan_Order">Zoltan_Order</a></b> and
<a href="ug_util_dd.html#DD_Find"><b>Zoltan_DD_Find</b></a>) require
the application to allocate memory for IDs. Memory for IDs can be allocated
as follows:
<blockquote><tt>
ZOLTAN_ID_PTR gids;<br>
int num_gids, int num_gid_entries;<br>
gids = (ZOLTAN_ID_PTR) <a href="ug_util_mem.html#Zoltan_Malloc">ZOLTAN_MALLOC</a>(num_gids * num_gid_entries * sizeof(ZOLTAN_ID_TYPE);<br>
</tt></blockquote>
The system call <i>malloc</i> may be used instead of
<a href="ug_util_mem.html#Zoltan_Malloc"><b>ZOLTAN_MALLOC</b></a>.
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_cpp.html">Next:&nbsp;
C++ Interface</a>&nbsp; |&nbsp; <a href="ug_intro.html">Previous:
Introduction</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

138
thirdParty/Zoltan/docs/ug_html/ug_util.html vendored Normal file
View File

@ -0,0 +1,138 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title> Zoltan User's Guide: Data Services</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_util_mem.html">Next</a>&nbsp; |&nbsp; <a href="ug_color_parallel.html">Previous</a></i></b></div>
<!--------------------------------------------------------------------------->
<h2>
<a NAME="Utilities"></a>Data Services and Utilities</h2>
Within Zoltan, several utilities are provided to simplify both application development and development of new algorithms
in the library.&nbsp;
They are separate from the Zoltan library so
that applications can use them independently of Zoltan, if desired.&nbsp; They are compiled separately
from Zoltan and can be archived in separate libraries.&nbsp; Instructions for
<a href="#Building Utilities">building the utilities</a>
and <a href="#Building Applications">applications</a> using them
are included below; individual library names are listed in the following documentation for each
package.&nbsp;
<p>
The packages available are listed below.
<blockquote><a href="ug_util_mem.html">Memory Management Utilities</a>
<br><a href="ug_util_comm.html">Unstructured Communication Utilities</a>
<br><a href="ug_util_dd.html">Distributed Directory Utility</a>
</blockquote>
<!--------------------------------------------------------------------------->
<h2>
<a NAME="Building Utilities"></a><hr>Building Utilities</h2>
The utilities provided with Zoltan have their own makefiles and can
be built separately from Zoltan.&nbsp; If the user
<a href="../ug_html/ug_usage.html#Building the Library">builds the Zoltan library</a>,
the utility libraries are
built automatically and copied to the appropriate <i>Zoltan/Obj_&lt;platform&gt;</i>
directory, where &lt;<i>platform</i>&gt; is specified through the
<a href="../ug_html/ug_usage.html#Building the Library">ZOLTAN_ARCH environment variable</a>.&nbsp;
Zoltan and the utilities share the
<a href="../ug_html/ug_usage.html#Building the Library"><i>Utilities/Config/Config.&lt;platform&gt;</i></a>
files specifying compilation paths for
various architectures.&nbsp;
If, however, a user wishes to use these
utilities without using Zoltan, he must build the libraries
separately.&nbsp;
<p>
The structure and use of makefiles for the utilities are similar
to <a href="ug_usage.html#Building the Library">Zoltan's makefiles</a>;
a top-level makefile includes rules for building each utility's
library.&nbsp; Object files and the utility libraries are stored in
a subdirectory <i>Obj_&lt;platform&gt;</i>, where &lt;<i>platform</i>&gt; is
a target architecture supported with a
<i><a href="../ug_html/ug_usage.html#Building the Library">Utilities/Config/Config.&lt;platform&gt;</i></a>
file.&nbsp; The command for compiling a particular utility follows:
<blockquote>
gmake ZOLTAN_ARCH=&lt;<i>platform</i>&gt; &lt;<i>library_name</i>&gt;
</blockquote>
where &lt;<i>library_name</i>&gt; is the name of the utility library, and
&lt;<i>platform</i>&gt; is the target architecture (corresponding to
<i>Utilities/Config/Config.&lt;platform&gt;</i>).&nbsp;
The &lt;<i>library_name</i>&gt; for each utility is included in the following documentation
for the utilities.&nbsp;
<p>
<!--------------------------------------------------------------------------->
<h2>
<a NAME="Building Applications"></a><hr>Building Applications</h2>
The utilities are designed so that they can easily be used separately
from Zoltan in applications.&nbsp;
To enable type-checking of arguments, the
function-prototypes file for a utility should be included
in all application source code files that directly access the utility.&nbsp;
The application must also link with the
appropriate utility library (and any other libraries on which
the utility depends).&nbsp; Library and function-prototype file names
for each utility are listed in the following documentation for the
utilities.&nbsp;
<p>
<!--------------------------------------------------------------------------->
<hr WIDTH="100%">
<br>[<a href="ug.html">Table of Contents</a>&nbsp; |&nbsp; <a href="ug_util_mem.html">Next:&nbsp;
Memory Management Utilities</a>&nbsp; |&nbsp; <a href="ug_color_parallel.html">Previous:&nbsp;
Parallel Coloring</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>

1265
thirdParty/Zoltan/docs/ug_html/ug_util_comm.html vendored Normal file
View File

File diff suppressed because it is too large Load Diff

922
thirdParty/Zoltan/docs/ug_html/ug_util_dd.html vendored Normal file
View File

@ -0,0 +1,922 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title> Zoltan User's Guide: Distributed Data Directory Utilities</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan Users's Guide</a>
&nbsp;|&nbsp;
<a href="ug_examples.html">Next</a>
&nbsp;|&nbsp;
<a href="ug_util_comm.html">Previous</a></i></b>
</div>
<!------------------------------------------------------------------------->
<h2>
<a NAME="Distributed Directory Utility"></a>Distributed Directory Utility
</h2>
A distributed directory may be viewed as a distributed hash table pointing to
the information stored in the directory.
An application may use this
directory utility to manage its objects' locations after data migrations or
to make information globally accessable.
A distributed
directory balances the load (in terms of memory and processing time)
and avoids the bottle neck of a centralized directory design.
<p>
This distributed directory module may be used alone or in conjunction
with Zoltan's load balancing capability and memory and communication
services. The user should note that external names (subroutines, etc.)
prefaced by Zoltan_DD_ are reserved when using this module.
Since the distributed directory uses collective communication,
it is important that all processors call the same function at the same time
in their processing.
<p>
The user initially creates an empty distributed directory using
<a href="#DD_Create">Zoltan_DD_Create</a>. Then each global ID (GID), which are the
directory keys, together with other optional information is added
to the directory using <a href="#DD_Update">Zoltan_DD_Update</a>.
The directory maintains the GID's basic information: local ID
(optional), part (optional), arbitrary user
data (optional), and the current data owner (optional). <a href="#DD_Update">
Zoltan_DD_Update</a> is also called after data migration or whenever it is
useful to update the information in the directory.
<a href="#DD_Find">Zoltan_DD_Find</a> returns the directory
information for a list of GIDs.
A selected list of GIDs may be removed from the
directory by <a href="#DD_Remove">Zoltan_DD_Remove</a>.
When the user has finished using
the directory, its memory is returned to the system by <a href="#DD_Destroy">
Zoltan_DD_Destroy</a>.
<p>
An object is known by its GID. Hashing provides very fast
lookup for the information associated with a GID in a two step
process. The first hash of the GID yields the processor number
owning the directory entry for that GID. The directory entry
owner remains constant even if the object associated with the GID migrates or changes
over time.
Second, a different hash algorithm on the GID looks up the
associated information in directory processor's hash table. The user
may optionally register their own (first) hash function to take
advantage of their knowledge of their GID naming scheme and the
GID's neighboring processors. See the documentation for
<a href="#DD_Set_Hash_Fn">Zoltan_DD_Set_Hash_Fn</a> for more information.
If no user hash function is registered, Zoltan's <b>
<a href="../dev_html/dev_services_hash.html">Zoltan_Hash</a></b> will be used. This
module's design was strongly influenced by the paper "Communication
Support for Adaptive Computation" by Pinar and Hendrickson.
<p>
Some users number their GIDs by giving the first "n" GIDs to processor 0,
the next "n" GIDs to processor 1, and so forth. The function
<a href="#DD_Set_Neighbor_Hash_Fn1">Zoltan_DD_Set_Neighbor_Hash_Fn1</a>
will provide efficient directory communication when these GIDs stay close to
their origin. The function <a href="#DD_Set_Neighbor_Hash_Fn2"></a>
Zoltan_DD_Set_Neighbor_Hash_Fn2 allows the specification of ranges of GIDs to
each processor for more flexibility. The source code for
<a href="#DD_Set_Neighbor_Hash_Fn1">DD_Set_Neighbor_Hash_Fn1</a> and
<a href="#DD_Set_Neighbor_Hash_Fn2">DD_Set_Neighbor_Hash_Fn2</a> provide
examples of how a user can create their own "hash" functions taking advantage
of their own GID naming convention.
<p>
The routine <a href="#DD_Print">Zoltan_DD_Print</a> will print the contents
of the directory. The companion routine <a href="#DD_Stats">Zoltan_DD_Stats</a>
prints out a summary of the hash table size, number of linked lists, and the
length of the longest linked list. This may be useful when the user
creates their own hash functions.
<p>
All modules use the following response to the debug_level:<br>
debug_level=0, Output is silent except for FATAL or MEMERR errors.<br>
debug_level=1, Turns on checking for legal, but possibly wrong conditions such as
updating the same directory multiple times in one update cycle.<br>
debug_level=5, Adds tracing information for the routines defined below.<br>
debug_level=6, Adds tracing information for all DD routines.<br>
debug_level=7, Adds tracing within each routine, <br>
debug_level>7, Adds information about each object when used.<br>
<p>
Calling DD_Stats or DD_Print is automatically verbose independent of the
debug_level.
<p>
The C++ interface to this utility is defined in the header file
<I>zoltan_dd_cpp.h</I> as the class <B>Zoltan_DD</B>. A single
<B>Zoltan_DD</B> object represents a distributed directory.
<p>
A Fortran90 interface is not yet available.
<p>
<hr>
<table>
<tr VALIGN=TOP>
<td WIDTH="50%"><b>Source code location:</b></td>
<td WIDTH="50%"><i>Utilities/DDirectory</i></td></tr>
<tr VALIGN=TOP>
<td><b>C Function prototypes file:</b></td>
<td><i>Utilities/DDirectory/zoltan_dd.h</i>
</td></tr>
<tr VALIGN=TOP>
<td><b>C++ class definition:</b></td>
<td><i>Utilities/DDirectory/zoltan_dd_cpp.h</i>
</td></tr>
<tr VALIGN=TOP>
<td><b>Library name:</b></td>
<td>libzoltan_dd.a</td></tr>
<tr VALIGN=TOP>
<td><b>Other libraries used by this library:</b></td>
<td>libmpi.a, libzoltan_mem.a, libzoltan_comm.a</td></tr>
</table>
<table>
<tr VALIGN=TOP>
<td COLSPAN="2">
<b>Routines:</b><blockquote>
<b><a href="#DD_Create">Zoltan_DD_Create</a></b>:&nbsp;
Allocates memory and initializes the directory.
<br><b><a href="#DD_Copy">Zoltan_DD_Copy</a></b>:&nbsp;
Allocates a new directory structure and copies an existing one to it.
<br><b><a href="#DD_Copy_To">Zoltan_DD_Copy_To</a></b>:&nbsp;
Copies one directory structure to another.
<br><b><a href="#DD_Destroy">Zoltan_DD_Destroy</a></b>:&nbsp;
Terminate the directory and frees its memory.
<br><b><a href="#DD_Update">Zoltan_DD_Update</a></b>:&nbsp;
Adds or updates GIDs' directory information.
<br><b><a href="#DD_Find">Zoltan_DD_Find</a></b>:&nbsp;
Returns GIDs' information (owner, local ID, etc.)
<br><b><a href="#DD_Remove">Zoltan_DD_Remove</a></b>:&nbsp;
Eliminates selected GIDs from the directory.
<br><b><a href="#DD_Stats">Zoltan_DD_Stats</a></b>:&nbsp;
Provides statistics about hash table & linked lists.
<br><b><a href="#DD_Print">Zoltan_DD_Print</a></b>:&nbsp;
Displays the contents (GIDs, etc) of each directory.
<br><b><a href="#DD_Set_Hash_Fn">Zoltan_DD_Set_Hash_Fn</a></b>:&nbsp;
Registers a user's optional hash function.
<br><b><a href="#DD_Set_Neighbor_Hash_Fn1">Zoltan_DD_Set_Neighbor_Hash_Fn1</a></b>:&nbsp;
Hash function with constant number of GIDs per processor.
<br><b><a href="#DD_Set_Neighbor_Hash_Fn2">Zoltan_DD_Set_Neighbor_Hash_Fn2</a></b>:&nbsp;
Hash function with variable number of GID's per processor.
</blockquote>
</td>
</tr>
<tr VALIGN=TOP><td COLSPAN="2"><b>Data Stuctures</b>:
<b></b>&nbsp;
<blockquote><b>struct Zoltan_DD_Struct</b>:&nbsp;State & storage used by all DD routines.
Users should not modify any
internal values in this structure. Users should only pass the
address of this structure to the other routines in this package.
</blockquote>
</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Create"></a>
<hr>
<table width="100%">
<tr valign=top width="100%">
<td width="10%">
<b>C:</b>
</td>
<td width="90%">
int <b>Zoltan_DD_Create </b>
(struct Zoltan_DD_Struct **<i>dd</i>,
MPI_Comm <i>comm</i>,
int <i>num_gid_entries</i>,
int <i>num_lid_entries</i>,
int <i>user_length</i>,
int <i>table_length</i>,
int <i>debug_level</i>);
</td>
</tr>
<tr valign=TOP>
<td width="10%">
<b>C++:</b>
</td>
<td width="90%">
<b>Zoltan_DD</b>(
const MPI_Comm & <i>comm</i>,
const int & <i>num_gid_entries</i>,
const int & <i>num_lid_entries</i>,
const int & <i>user_length</i>,
const int & <i>table_length</i>,
const int & <i>debug_level</i>);
<br>
&nbsp;&nbsp;&nbsp;or
<br>
<b>Zoltan_DD</b>();
<br>
<b>Zoltan_DD::Create</b>(
const MPI_Comm & <i>comm</i>,
const int & <i>num_gid_entries</i>,
const int & <i>num_lid_entries</i>,
const int & <i>user_length</i>,
const int & <i>table_length</i>,
const int & <i>debug_level</i>);
</td>
</tr>
</table>
<hr>
<b>Zoltan_DD_Create</b> allocates and initializes memory for the Zoltan_DD_Struct
structure. It must be called before any other distributed directory
routines. MPI must be initialized prior to calling this routine.
<p>
The Zoltan_DD_Struct must be passed to all other distributed directory
routines. The MPI Comm argument designates the processors used for the
distributed directory. The MPI Comm argument is duplicated and stored for
later use. The length of the GID, length of the LID, and the length of the
optional user data (user_length) must be consistent for all processors.
<p>
<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;dd</i></td>
<td> Structure maintains directory state and hash table.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;comm</i></td>
<td>MPI comm duplicated and stored specifying directory processors.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;num_gid_entries</i></td>
<td>Length (number of ZOLTAN_ID_TYPE) of GID.</td>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;num_lid_entries</i></td>
<td>Length (number of ZOLTAN_ID_TYPE) of local ID or zero to ignore local IDs.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;user_length</i></td>
<td>Length (number of char) of user defined data field (optional, may be zero).</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;table_length</i></td>
<td>Length of hash table (zero forces default value of <b>100,000</b> slots).
For large problems, this value should be increased to approximately
the number of
global GIDs / number of processors (if you have enough memory) in order to
improve performance.
</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;debug_level</i></td>
<td>Legal values range in [0,9]. Sets the output response to various error
conditions where 9 is the most verbose.</td></tr>
<tr>
<td><b>Returned Value:</b></td><td></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td></tr>
</table>
<p>
ZOLTAN_FATAL is returned for MPI problems or if <i>num_gid_entries,
num_lid_entries,</i> or <i>user_length
</i> do
not match globally.
<br>
ZOLTAN_MEMERR is returned if sufficient memory can not be allocated.
<br>
ZOLTAN_OK is the normal return value.
<p>
In the C++ interface, the distributed directory
is represented by a <B>Zoltan_DD</B> object. It is created when the
<B>Zoltan_DD</B> constructor executes. There are two constructors. The
first one listed above uses parameters to initialize the distributed
directory. The
second constructor does not, but it can subsequently be initialized
with a call to <B>Zoltan_DD::Create()</B>.
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Copy"></a>
<hr>
<table width="100%">
<tr valign=top width="100%">
<td width="10%" >
<b>C:</b>
</td>
<td width="90%" >
struct Zoltan_DD_Struct &nbsp *<b>Zoltan_DD_Copy</b> (struct Zoltan_DD_Struct *<i>from</i>);
</td>
</tr>
<tr valign=top>
<td width="10%" >
<b>C++:</b>
</td>
<td width="90%" >
<b>Zoltan_DD</b>(const Zoltan_DD &dd);
</td>
</tr>
</table>
<hr>
This routine creates a new distributed directory structure and copies
an existing one to it. The corresponding routine in the C++ library
is the Zoltan_DD copy constructor.
<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;from</i></td>
<td>The existing directory structure which will be copied to the new one.</td></tr>
<tr valign=top>
<td><b>Returned Value:</b></td><td></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;struct Zoltan_DD_Struct *</td>
<td valign=top>The newly created directory structure.</td></tr>
</table>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Copy_To"></a>
<hr>
<table width="100%">
<tr valign=top width="100%">
<td width="10%" >
<b>C:</b>
</td>
<td width="90%" >
int <b>Zoltan_DD_Copy_To</b> (struct Zoltan_DD_Struct **<i>to</i>, struct Zoltan_DD_Struct *<i>from</i>);
</td>
</tr>
<tr valign=top width="100%">
<td width="10%">
<b>C++:</b>
</td>
<td width="90%">
Zoltan_DD & <b>operator=</b>(const Zoltan_DD &dd);
</td>
</tr>
</table>
<hr>
This routine copies one distributed directory structure to another.
The corresponding method in the C++ library
is the Zoltan_DD class copy operator.
<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;to</i></td>
<td>A pointer to a pointer to the target structure. The structure will be destroyed and the pointer set to NULL before proceeding with the copy.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;from</i></td>
<td>A pointer to the source structure. The contents of this structure will be copied to the target structure.</td></tr>
<tr>
<td><b>Returned Value:</b></td><td></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td></tr>
</table>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Destroy"></a>
<hr>
<table width="100%">
<tr valign=top>
<td width="10%">
<b>C:</b>
</td>
<td width="90%">
void <b>Zoltan_DD_Destroy</b> (struct Zoltan_DD_Struct **<i>dd</i>);
</td>
</tr>
<tr valign=top width="100%">
<td width="10%">
<b>C++:</b>
</td>
<td width="90%">
<b>~Zoltan_DD();</b>
</td>
</tr>
</table>
<hr>
This routine frees all memory allocated for the distributed directory.
No calls to any distributed directory functions using this
Zoltan_DD_Struct are permitted after
calling this routine. MPI is necessary for this routine only
to free the previously saved MPI comm.
<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;dd</i></td>
<td>Directory structure to be deallocated.</td></tr>
<tr>
<td><b>Returned Value:</b></td><td></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;void</td>
<td>NONE</td></tr>
</table>
<p>
There is no explicit <b>Destroy</b> method in the C++ <b>Zoltan_DD</b>
class. The object is deallocated when its destructor is called.
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Update"></a>
<hr>
<table width="100%">
<tr valign=top>
<td width="10%">
<b>C:</b><br>
</td>
<td width="90%">
int <b>Zoltan_DD_Update</b>
(struct Zoltan_DD_Struct *<i>dd</i>,
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>gid</i>,
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>lid</i>,
char *<i>user</i>,
int *<i>part</i>,
int <i>count</i>);
</td>
</tr>
<tr valign=top width="100%">
<td width="10%">
<b>C++:</b>
</td>
<td width="90%">
int <b>Zoltan_DD::Update</b>(
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>gid</i>,
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>lid</i>,
char *<i>user</i>,
int *<i>part</i>,
const int & <i>count</i>);
</td>
</tr>
</table>
<hr>
<b>Zoltan_DD_Update</b> takes a list of GIDs and corresponding lists of
optional local IDs, optional user data, and optional parts. This
routine updates the information for existing directory entries or creates
a new entry (filled with given data) if a GID is not found. NULL
lists should be passed for optional arguments not desired.
This function should be called initially and
whenever objects are migrated to keep the distributed directory current.
<p>
The user can set the debug level argument in <b>Zoltan_DD_Create</b>
to determine the module's response to multiple updates for any GID
within one update cycle.
<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;<i>dd</i></td>
<td>Distributed directory structure state information.</td></tr>
<tr><td VALIGN=Top><i>&nbsp;&nbsp;&nbsp;gid</i></td>
<td>List of GIDs to update (in).</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>lid</i></td>
<td>List of corresponding local IDs (optional) (in).
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>user</i></td>
<td>List of corresponding user data (optional) (in).</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>part</i></td>
<td>List of corresponding parts (optional) (in).</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>count</i></td>
<td>Number of GIDs in update list.</td></tr>
<tr>
<td><b>Returned Value:</b></td><td></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td></tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Find"></a>
<hr>
<table width="100%">
<tr valign=top>
<td width="10%">
<b>C:</b><br>
</td>
<td width="90%">
int <b>Zoltan_DD_Find</b>
(struct Zoltan_DD_Struct *<i>dd</i>,
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>gid</i>,
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>lid</i>,
char *<i>data</i>,
int *<i>part</i>,
int <i>count</i>,
int *<i>owner</i>);
</td>
</tr>
<tr valign=top width="100%">
<td width="10%">
<b>C++:</b>
</td>
<td width="90%">
int <b>Zoltan_DD::Find</b>(
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>gid</i>,
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>lid</i>,
char *<i>data</i>,
int *<i>part</i>,
const int & <i>count</i>,
int *<i>owner</i>) const;
</td>
</tr>
</table>
<hr>
Given a list of GIDs, <b>Zoltan_DD_Find</b> returns corresponding
lists of the GIDs' owners, local IDs, parts, data owners, and optional
user data. NULL lists must be provided for optional information not
being used.
<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;dd</i></td>
<td>Distributed directory structure state information.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>gid</i></td>
<td>List of GIDs whose information is requested.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>lid</i></td>
<td>Corresponding list of local IDs (optional) (out).</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>data</i></td>
<td>Corresponding list of user data (optional) (out).</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>part</i></td>
<td>Corresponding list of parts (optional) (out).</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>count</i></td>
<td>Count of GIDs in above list.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>owner</i></td>
<td>Corresponding list of data owners (out).</td></tr>
<tr>
<td><b>Returned Value:</b></td><td></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td></tr>
</table>
<p>
ZOLTAN_OK is the normal return.
<br>
ZOLTAN_WARN is returned when at
least one GID in the <i>gid</i> list is not found AND debug level > 0.
<br>
ZOLTAN_MEMERR is returned whenever memory can not be allocated.
<br>
ZOLTAN_FATAL is returned whenever there is a problem with the input arguments (such as
<i>dd</i> being NULL) or communications error.
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Remove"></a>
<hr>
<table width="100%">
<tr valign=top>
<td width="10%">
<b>C:</b><br>
</td>
<td width="90%">
int <b>Zoltan_DD_Remove</b>
(struct Zoltan_DD_Struct *<i>dd</i>,
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>gid</i>,
int <i>count</i>);
</td>
</tr>
<tr valign=top width="100%">
<td width="10%">
<b>C++:</b>
</td>
<td width="90%">
int <b>Zoltan_DD::Remove</b>(
<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>gid</i>,
const int & <i>count</i>);
</td>
</tr>
</table>
<hr>
<b>Zoltan_DD_Remove</b> takes a list of GIDs and removes all of
their information from the distributed directory.
<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;dd</i></td>
<td>Distributed directory structure state information.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>gid</i></td>
<td>List of GIDs to eliminate from the directory.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>count</i></td>
<td>Number of GIDs to be removed.</td></tr>
<tr>
<td><b>Returned Value:</b></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td></tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Set_Hash_Fn"></a>
<hr>
<table width="100%">
<tr valign=top>
<td width="10%">
<b>C:</b><br>
</td>
<td width="90%">
void <b>Zoltan_DD_Set_Hash_Fn</b>
(struct Zoltan_DD_Struct *<i>dd</i>,
unsigned int (*<i>hash</i>) (<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a>, int, unsigned int));
</td>
</tr>
<tr valign=top width="100%">
<td width="10%">
<b>C++:</b>
</td>
<td width="90%">
void <b>Zoltan_DD::Set_Hash_Fn</b>(
unsigned int (*<i>hash</i>) (<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a>, int, unsigned int));
</td>
</tr>
</table>
<hr>
Enables the user to register a new hash function for the distributed
directory. (If this routine is not called, the default hash function
<b><a href="../dev_html/dev_services_hash.html">Zoltan_Hash</a></b> will be used automatically.) This hash function determines
which processor maintains the distributed directory entry for a given
GID. Inexperienced users do not need this routine.
<p>
Experienced users may elect to create their own hash function based on
their knowledge of their GID naming scheme. The user's hash
function must have calling arguments compatible with <b><a href="../dev_html/dev_services_hash.html">Zoltan_Hash</a></b>.
The final argument, <i>nprocs</i>, is the number of processors in
the communicator passed to <a href="#DD_Create"><b>Zoltan_DD_Create</b></a>.
Consider that a user has defined a hash function, myhash, as<br>
<p>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
extern int total_num_gid; <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
unsigned int myhash(<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> gid, int length, unsigned int nproc)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
/* Assuming a processor is more likely to query GIDs that are numerically
close to the GIDs it owns, */ <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
/* this hash function tries to store the gid's directory information
near the gid's owning processor's neighborhood. */ <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
/* GID length is one ; total_num_gid is a global variable with the total number of GIDs in the application. */<br><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
return ((*gid * nproc) / total_num_gid); <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
}<br>
<p>
Then the call to register this hash function is:<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Zoltan_DD_Set_Hash(dd, myhash);<br>
<p>
<p>
<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;<i>dd</i></td>
<td>Distributed directory structure state information.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>hash</i></td>
<td>Name of user's hash function.</td></tr>
<tr>
<td><b>Returned Value:</b></td><td></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;void</td>
<td>NONE</td></tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Stats"></a>
<hr>
<table width="100%">
<tr valign=top>
<td width="10%">
<b>C:</b><br>
</td>
<td width="90%">
void <b>Zoltan_DD_Stats</b>
(struct Zoltan_DD_Struct *<i>dd</i>);
</td>
</tr>
<tr valign=top width="100%">
<td width="10%">
<b>C++:</b>
</td>
<td width="90%">
void <b>Zoltan_DD::Stats</b>() const;
</td>
</tr>
</table>
<hr>
This routine prints out summary information about the local distributed
directory. It includes the hash table length, number of GIDs stored in
the local directory, the number of linked lists, and the length of the
longest linked list. The debug level (set by an argument to
<b>Zoltan_DD_Create</b> controls this routine's verbosity.
<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;dd</i></td>
<td>Distributed directory structure for state information</td></tr>
<tr>
<td><b>Returned Value:</b></td><td></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;void</td>
<td>NONE</td></tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Set_Neighbor_Hash_Fn1"></a>
<hr>
int <b>Zoltan_DD_Set_Neighbor_Hash_Fn1</b>
(struct Zoltan_DD_Struct *<i>dd</i>,
int <i>size</i>);
<hr>
This routine associates the first size GIDs to proc 0, the next size to
proc 1, etc. It assumes the GIDs are consecutive numbers. It assumes
that GIDs primarily stay near their original owner. The GID length is
assumed to be 1. GIDs outside of the range are evenly distributed among
the processors via modulo(number of processors). This is a model for the user to develop
their own similar routine.
<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;<i>dd</i></td>
<td>Distributed directory structure state information.</td></tr>
<tr><td VALIGN=Top><i>&nbsp;&nbsp;&nbsp;<i>size</i></td>
<td>Number of consecutive GIDs associated with a processor.</td></tr>
<tr>
<td><b>Returned Value:</b></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td></tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Set_Neighbor_Hash_Fn2"></a>
<hr>
int <b>Zoltan_DD_Set_Neighbor_Hash_Fn2</b>
(struct Zoltan_DD_Struct *dd,
int *<i>proc</i>,
int *<i>low</i>,
int *<i>high</i>,
int <i>n</i>);
<hr>
This routine allows the user to specify a beginning and ending GID
"numbers" per directory processor. It assumes that GIDs primarily stay
near their original owner. It requires that the numbers of high, low, &
proc entries are all n. It assumes the GID length is 1. It is a model for
the user to develop their own similar routine. Users should note the
registration of a cleanup routine to free local static memory when the
distributed directory is destroyed. GIDs outside the range specified by
high and low lists are evenly distributed among the processors via modulo
(number of processors).
<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;dd</i></td>
<td>Distributed directory structure state information.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>proc</i></td>
<td>List of processor ids labeling for corresponding high, low value.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>low</i></td>
<td>List of low GID limits corresponding to proc list.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>high</i></td>
<td>List of high GID limits corresponding to proc list.</td></tr>
<tr><td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>n</i></td>
<td>Number of elements in the above lists. Should be number of processors!</td></tr>
<tr>
<td><b>Returned Value:</b></td><td></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td></tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="DD_Print"></a>
<hr>
<table width="100%">
<tr valign=top>
<td width="10%">
<b>C:</b>
</td>
<td width="90%">
int <b>Zoltan_DD_Print</b> (struct Zoltan_DD_Struct *<i>dd</i>);
</td>
</tr>
<tr valign=top width="100%">
<td width="10%">
<b>C++:</b>
</td>
<td width="90%">
int <b>Zoltan_DD::Print</b> () const;
</td>
</tr>
</table>
<hr>
This utility displays (to stdout) the entire contents of the distributed
directory at one line per GID.
<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;dd</i></td>
<td>Distributed directory structure state information.</td></tr>
<tr>
<td><b>Returned Value:</b></td></tr>
<tr><td>&nbsp;&nbsp;&nbsp;int</td>
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td></tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<hr>
<p ALIGN=CENTER><b>User's Notes</b>
<p>
Because Zoltan places no restrictions on the content or length of GIDs,
hashing does not guarantee a balanced distribution of objects in
the distributed directory. Note also, the worst case behavior of a hash
table lookup is very bad (essentially becoming a linear search).
Fortunately, the average behavior is very good! The user may specify
their own hash function via <a href="#DD_Set_Hash_Fn">
Zoltan_DD_Set_Hash_Fn</a> to improve
performance.
<p>
This software module is built on top of the Zoltan Communications
functions for efficiency. Improvements to the communications library
will automatically benefit the distributed directory.
<p>
<hr WIDTH="100%">
<br>[<a href="ug.html">Table of Contents</a>&nbsp; |&nbsp; <a href="ug_examples.html">Next:&nbsp;
Examples of Zoltan Usage</a>&nbsp; |&nbsp; <a href="ug_util_comm.html">Previous:&nbsp;
Unstructured Communication Utilities</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</body>
</html>

817
thirdParty/Zoltan/docs/ug_html/ug_util_mem.html vendored Normal file
View File

@ -0,0 +1,817 @@
<!-------- @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.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<title> Zoltan User's Guide: Memory Management Utilities</title>
</head>
<body bgcolor="#FFFFFF">
<div align=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_util_comm.html">Next</a>&nbsp; |&nbsp; <a href="ug_util.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->
<h2>
<a NAME="Memory"></a>Memory Management Utilities</h2>
This package consists of wrappers around the standard C memory
allocation and deallocation routines which add error-checking and
<a href="#Debug_Memory">debugging capabilities</a>. These routines
are packaged separately from Zoltan to allow their independent
use in other applications. A Fortran90 interface is not yet available.
C++ programmers can include the header file "zoltan_mem.h" and use the
C functions. This header file, and in fact all of Zoltan's C language header
files, are surrounded by an <B>extern "C" {}</B> declaration to
prevent name mangling when compiled with a C++ compiler.
<p>
<hr>
<table>
<tr VALIGN=TOP>
<td WIDTH="50%">
<b>Source code location:</b>
</td>
<td WIDTH="50%">
<i>Utilities/Memory</i>
</td>
</tr>
<tr VALIGN=TOP>
<td>
<b>Function prototypes file:</b>
</td>
<td>
<i>Utilities/Memory/zoltan_mem.h</i> or <i>include/zoltan_mem.h</i>
</td>
</tr>
<tr VALIGN=TOP>
<td>
<b>Library name:</b>
</td>
<td>
libzoltan_mem.a
</td>
</tr>
<tr VALIGN=TOP>
<td>
<b>Other libraries used by this library:</b>
</td>
<td>
libmpi.a. (See <a href="#MPI_NOTE">note</a> below.)
</td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2">
<b>Routines:</b>
<blockquote><b><a href="#Zoltan_Array_Alloc">Zoltan_Array_Alloc</a></b>:&nbsp;
Allocates arrays of dimension <i>n</i>, <i>n</i>=0,1,...,4
<br><b><a href="#Zoltan_Malloc">Zoltan_Malloc</a></b>:&nbsp; Wrapper for system
malloc.
<br><b><a href="#Zoltan_Calloc">Zoltan_Calloc</a></b>:&nbsp; Wrapper for system
calloc.
<br><b><a href="#Zoltan_Realloc">Zoltan_Realloc</a></b>:&nbsp; Wrapper for system
realloc.
<br><b><a href="#Zoltan_Free">Zoltan_Free</a></b>:&nbsp; Frees memory and sets
the pointer to NULL.
<br><b><a href="#Zoltan_Memory_Debug">Zoltan_Memory_Debug</a></b>:&nbsp; Sets
the debug level used by the memory utilities; see
the <a href="#Debug_Memory">description</a> below.
<br><b><a href="#Zoltan_Memory_Stats">Zoltan_Memory_Stats</a></b>:&nbsp; Prints
<a href="#Debug_Memory">memory debugging</a> statistics, such as memory
leak information.
<br><b><a href="#Zoltan_Memory_Usage">Zoltan_Memory_Usage</a></b>:&nbsp; Returns
user-specified information about memory usage (i.e. maximum memory used, total
memory currently allocated).
<br><b><a href="#Zoltan_Memory_Reset">Zoltan_Memory_Reset</a></b>:&nbsp; Sets
the memory usage total specified by the user (i.e. maximum memory used, total
memory currently allocated) back to zero.
</blockquote>
</td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2">
<b>Use in Zoltan:</b>
<blockquote>
The memory management utility routines are used extensively in Zoltan and
in some individual algorithms. Zoltan developers use these routines
directly for most memory management, taking advantage of the error checking
and <a href="#Debug_Memory">debugging capabilities</a> of the library.
<p>
Rather than call <a href="#Zoltan_Memory_Debug"><b>Zoltan_Memory_Debug</b></a>
directly, applications using Zoltan can set the
<a href="#Debug_Memory"><b>DEBUG_MEMORY</b></a> parameter
used by this utility through calls to
<a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param"><b>Zoltan_Set_Param</b></a>.
</blockquote>
</td>
</tr>
<tr valign=top>
<td colspan="2">
<a name="MPI_NOTE"></a>
<b>Note on MPI usage:</b>
<blockquote>
MPI is used only to obtain the processor number (through a call to
MPI_Comm_rank) for print statements and error messages.
If an application does not link with MPI, the memory utilities should be
compiled with -DZOLTAN_NO_MPI; all output will then appear to be from
processor zero, even if it is actually from other processors.
</blockquote>
</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Array_Alloc"></a>
<hr>
double *<b>Zoltan_Array_Alloc</b>(char *<i>
file</i>, int <i>line</i>, int <i>n</i>, int <i>d1</i>, int <i>d2</i>,
..., int <i>dn</i>, int <i>size</i>);&nbsp;
<hr>
The <b>Zoltan_Array_Alloc</b> routine dynamically allocates an array of
dimension <i>n</i>, <i>n </i>= 0, 1, ..., 4 with size (<i>d1</i> x <i>d2</i>
x ... x <i>dn</i>). It is intended to be used for 2, 3 and 4 dimensional
arrays; <b><a href="#Zoltan_Malloc">Zoltan_Malloc</a></b> should be used for the simpler cases. The memory
allocated by <b>Zoltan_Array_Alloc</b> is contiguous, and can be freed by a
single call to <b><a href="#Zoltan_Free">Zoltan_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; file</i></td>
<td>A string containing the name of the file calling the function. The
<i>__FILE__</i>
macro can be passed as this argument. This argument is useful for debugging
memory allocation problems.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; line</i></td>
<td>The line number within <i>file</i> of the call to the function. The
<i>__LINE__</i>
macro can be passed as this argument. This argument is useful for debugging
memory allocation problems.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; n</i></td>
<td>The number of dimensions in the array to be allocated. Valid values
are 0, 1, 2, 3, or 4.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>d1</i>, <i>d2</i>, ..., <i>dn</i></td>
<td>The size of each dimension to be allocated. One argument is included
for each dimension.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; <i>size</i></td>
<td>The size (in bytes) of the data objects to be stored in the array.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; double *</td>
<td>A pointer to the starting address of the <i>n</i>-dimensional array,
or NULL if the allocation fails.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Example:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>int **<i> x</i> = (int **) <b>Zoltan_Array_Alloc</b> (<i> __FILE__</i>
, <i>__LINE__</i> , 2, 5, 6, <i>sizeof</i> (int));</td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>Allocates a two-dimensional, 5x6-element array of integers.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Malloc"></a>
<hr>
double *<b>Zoltan_Malloc</b>(size_t <i>n</i>, char
*<i> file</i> , int <i>line</i>);&nbsp;
<hr>
The <b>Zoltan_Malloc</b> function is a wrapper around the standard C malloc
routine. It allocates a block of memory of size <i>n</i> bytes. The principle
advantage of using the wrapper is that it allows memory leaks to be tracked
via the DEBUG_MEMORY variable (set in <a href="#Zoltan_Memory_Debug"><b>Zoltan_Memory_Debug</b></a>).
<p>A macro <b>ZOLTAN_MALLOC</b> is defined in <i>zoltan_mem.h</i>.
It takes the argument <i>n</i>, and adds the <i>__FILE__</i> and <i>__LINE__</i>
macros to the argument list of the <b>Zoltan_Malloc</b> call:
<blockquote>#define&nbsp;&nbsp;&nbsp; <b>ZOLTAN_MALLOC</b>(<i>n</i>)&nbsp;&nbsp;
<b>Zoltan_Malloc</b>((<i>n</i>), <i>__FILE__</i>, <i>__LINE__</i>)</blockquote>
Using this macro, the developer gains the file and line debugging information
without having to type file and line information in each memory allocation
call.
<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> n</i></td>
<td>The size (in bytes) of the memory-allocation request.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; file</i></td>
<td>A string containing the name of the file calling the function. The
<i>__FILE__</i>
macro can be passed as this argument. This argument is useful for debugging
memory allocation problems.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; line</i></td>
<td>The line number within <i>file</i> of the call to the function. The
<i>__LINE__</i>
macro can be passed as this argument. This argument is useful for debugging
memory allocation problems.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; double *</td>
<td>A pointer to the starting address of memory allocated.&nbsp; NULL is
returned if <i>n</i> = 0 or the routine is unsuccessful.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Example:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>struct <b>Zoltan_Struct</b> *<i>b</i> = (struct <b>Zoltan_Struct</b> *) <b>ZOLTAN_MALLOC</b>(<i>sizeof</i>(struct
<b>Zoltan_Struct</b>));</td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>Allocates memory for one <b>Zoltan_Struct</b> data structure.&nbsp;</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Calloc"></a>
<hr>
double *<b>Zoltan_Calloc</b>(size_t <i>num</i>, size_t <i>size</i>, char
*<i> file</i>, int <i>line</i>);&nbsp;
<hr>
The <b>Zoltan_Calloc</b> function is a wrapper around the standard C calloc
routine. It allocates a block of memory of size <i>num * size </i> bytes and
initializes the memory to zeros. The principle
advantage of using the wrapper is that it allows memory leaks to be tracked
via the DEBUG_MEMORY variable (set in <a href="#Zoltan_Set_Memory_Debug"><b>Zoltan_Set_Memory_Debug</b></a>).
<p>A macro <b>ZOLTAN_CALLOC</b> is defined in <i>zoltan_mem.h</i>.
It takes the arguments <i>num</i> and <i>size</i>, and adds the <i>__FILE__</i> and <i>__LINE__</i>
macros to the argument list of the <b>Zoltan_Calloc</b> call:
<blockquote>#define&nbsp;&nbsp;&nbsp; <b>ZOLTAN_CALLOC</b>(<i>num</i>, <i>size</i>)&nbsp;&nbsp;
<b>Zoltan_Calloc</b>((<i>num</i>), (<i>size</i>), <i>__FILE__</i>, <i>__LINE__</i>)</blockquote>
Using this macro, the developer gains the file and line debugging information
without having to type file and line information in each memory allocation
call.
<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> num</i></td>
<td>The number of elements of the following <i>size</i> to allocate.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp;<i> size</i></td>
<td>The size of each element. Hence, the total allocation
is <i>num</i> * <i>size</i> bytes.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; file</i></td>
<td>A string containing the name of the file calling the function. The
<i>__FILE__</i>
macro can be passed as this argument. This argument is useful for debugging
memory allocation problems.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; line</i></td>
<td>The line number within <i>file</i> of the call to the function. The
<i>__LINE__</i>
macro can be passed as this argument. This argument is useful for debugging
memory allocation problems.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; double *</td>
<td>A pointer to the starting address of memory allocated.&nbsp; NULL is
returned if <i>n</i> = 0 or the routine is unsuccessful.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Example:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>int *<i>b</i> = (int *) <b>ZOLTAN_CALLOC</b>(
<i>10</i>, <i>sizeof</i>(int));</td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>Allocates memory for 10 integers and initializes the memory to zeros.&nbsp;</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Realloc"></a>
<hr>
double *<b>Zoltan_Realloc</b>(void *<i>ptr</i>,
size_t <i>n</i>, char *<i>file</i>, int <i>line</i>);&nbsp;
<hr>
The <b>Zoltan_Realloc</b> function is a "safe" version of realloc. It changes
the size of the object pointed to by <i>ptr</i> to <i>n</i> bytes. The
contents of <i>ptr</i> are unchanged up to a minimum of the old and new
sizes. Error tests ensuring that <i>n</i> is a positive number and that
space is available to be allocated are performed.
<p>A macro <b>ZOLTAN_REALLOC</b> is defined in <i>zoltan_mem.h</i>.
It takes the arguments <i>ptr</i> and <i>n</i>, and adds the <i>__FILE__</i>
and <i>__LINE__</i> macros to the argument list of the <b>Zoltan_Realloc</b>
call:
<blockquote>#define&nbsp;&nbsp;&nbsp; <b>ZOLTAN_REALLOC</b>(<i>ptr</i>, <i>n</i>)&nbsp;
<b>Zoltan_Realloc</b>((<i>ptr</i>), (<i>n</i>), <i>__FILE__</i>, <i>__LINE__</i>)</blockquote>
Using this macro, the developer gains the file and line debugging information
without having to type file and line information in each memory allocation
call.
<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>ptr</i></td>
<td>Pointer to allocated memory to be re-sized.</td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp;<i> n</i></td>
<td>The size (in bytes) of the memory-allocation request.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; file</i></td>
<td>A string containing the name of the file calling the function. The
<i>__FILE__</i>
macro can be passed as this argument. This argument is useful for debugging
memory allocation problems.</td>
</tr>
<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; line</i></td>
<td>The line number within <i>file</i> of the call to the function. The
<i>__LINE__</i>
macro can be passed as this argument. This argument is useful for debugging
memory allocation problems.</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; double *</td>
<td>A pointer to the starting address of memory allocated.&nbsp; If the
routine is unsuccessful, NULL is returned and *<i>ptr</i> is unchanged.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Example:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td><i>int</i> <i>n</i> = <i>sizeof</i>(struct <b>Zoltan_Struct</b>);
<br><i>int</i> *<i>b</i> = (<i>int </i>*) <b><a href="#Zoltan_Malloc">ZOLTAN_MALLOC</a></b>
(<i>n</i>));&nbsp;
<br><i>b</i> = (<i>int </i>*) <b>ZOLTAN_REALLOC</b> (<i>b</i>, 2*<i>n</i>);</td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>Reallocates memory for <i>b</i> from length <i>n</i> to length 2*<i>n</i>.&nbsp;</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Free"></a>
<hr>
void <b>Zoltan_Free</b>(void **<i>ptr</i>, char *<i>
file</i> , int <i>line</i>);&nbsp;
<hr>
The <b>Zoltan_Free</b> function calls the system's "free" function for the
memory pointed to by <i>*ptr</i>. Note that the argument to this routine
has an extra level of indirection when compared to the standard C "free"
call. This allows the pointer being freed to be set to NULL, which can
help find errors in which a pointer is used after it is deallocated. Error
checking is performed to prevent attempts to free NULL pointers. When <b>Zoltan_Free</b>
is used with the DEBUG_MEMORY options (set in <a href="#Zoltan_Memory_Debug"><b>Zoltan_Memory_Debug</b></a>), it can help identify memory leaks.
<p>A macro <b>ZOLTAN_FREE</b> is defined in <i>zoltan_mem.h</i>. It
takes the argument <i>ptr</i>, and adds the <i>__FILE__</i> and <i>__LINE__</i>
macros to the argument list of the <b>Zoltan_Free</b> call:
<blockquote>#define&nbsp;&nbsp;&nbsp; <b>ZOLTAN_FREE</b>(<i>ptr</i>)&nbsp;&nbsp;
<b>Zoltan_Free</b>((void **)(<i>ptr</i>), <i>__FILE__</i>, <i>__LINE__</i>)</blockquote>
Using this macro, the developer gains the file and line debugging information
without having to type file and line information in each memory allocation
call.
<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>ptr</i></td>
<td>Address of a pointer to the memory to be freed. Upon return, <i>ptr</i>
is set to NULL.</td>
</tr>
<tr>
<td VALIGN=TOP><b>Example:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td><b>ZOLTAN_FREE</b>(&amp;<i> x</i>);</td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>Frees memory associated with the variable <i>x</i>; upon return, <i>x</i>
is NULL.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<hr><a NAME="Debug_Memory"></a>
<h3>
<b>Debugging Memory Errors</b></h3>
One important reason to use the memory-management utilities' wrappers around the system memory
routines is to facilitate debugging of memory problems.&nbsp Various amounts of information can
about memory allocation and deallocation are stored, depending on the debug level set
through a call to <a href="#Zoltan_Memory_Debug"><b>Zoltan_Memory_Debug</b></a>.&nbsp This information is printed either when an error or
warning occurs, or when <a href="#Zoltan_Memory_Stats"><b>Zoltan_Memory_Stats</b></a> is called.&nbsp
We have found values of one and two to
be very helpful in our development efforts.&nbsp; The routine <a href="#Zoltan_Memory_Usage">
<b>Zoltan_Memory_Usage</b></a> can be called to return user-specified information about memory
utilization to the user's program, and <a href="#Zoltan_Memory_Reset">
<b>Zoltan_Memory_Reset</b></a> can be called to set totals back to zero.
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Memory_Debug"></a>
<hr>
void <b>Zoltan_Memory_Debug</b>(int <i>new_level</i>);
<hr>
The <b>Zoltan_Memory_Debug</b> function sets the level of memory debugging to
be used.
<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>new_level</i></td>
<td>Integer indicating the amount of debugging to use.&nbsp Valid options include:
<blockquote>
0 -- No debugging.
<br>
1 -- The number of calls to <a href="#Zoltan_Malloc"><b>Zoltan_Malloc</b></a> and
<a href="#Zoltan_Free"><b>Zoltan_Free</b></a>
are tallied, and can be printed by a call to <a href="#Zoltan_Memory_Stats"><b>Zoltan_Memory_Stats</b></a>.
<br>
2 -- A list of
all calls to <a href="#Zoltan_Malloc"><b>Zoltan_Malloc</b></a> which have
not yet been freed is kept. This list
is printed by <a href="#Zoltan_Memory_Stats"><b>Zoltan_Memory_Stats</b></a>
(useful for detecting memory leaks).
Any calls to <a href="#Zoltan_Free"><b>Zoltan_Free</b></a> with addresses
not in this list trigger warning messages. (Note that allocations that
occurred prior to setting the debug level to 2 will not be in this
list and thus can generate spurious warnings.)
<br>
3 -- Information about each allocation is printed as it happens.
</blockquote>
</td>
</tr>
<tr>
<td VALIGN=TOP><b>Default:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td>Memory debug level is 1.</td>
</tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Memory_Stats"></a>
<hr>
void <b>Zoltan_Memory_Stats</b>();
<hr>
The <b>Zoltan_Memory_Stats</b> function prints information about memory allocation
and deallocation.&nbsp; The amount of information printed is determined by the
debug level set through a call to <a href="#Zoltan_Memory_Debug"><b>Zoltan_Memory_Debug</b></a>.
<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></td>
<td>None.</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Memory_Usage"></a>
<hr>
size_t <b>Zoltan_Memory_Usage</b>(int <i>type</i>);
<hr>
The <b>Zoltan_Memory_Usage</b> function returns information about memory
utilization.
The memory debug level (set through a call to <a href="#Zoltan_Set_Memory_Debug"><b>Zoltan_Set_Memory_Debug</b></a>) must be at least 2 for this function to
return non-zero values.
<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>type</i></td>
<td>Integer to request type of information required.&nbsp These integers
are defined in <i>zoltan_mem.h</i>. Valid options include:
<blockquote>
ZOLTAN_MEM_STAT_TOTAL -- The function will return the current total memory
allocated via Zoltan's memory allocation routines.
<br>
ZOLTAN_MEM_STAT_MAXIMUM -- The function will return the maximum total memory
allocated via Zoltan's memory allocation routines up to this point.
</blockquote>
</td>
</tr>
<tr>
<td VALIGN=TOP><b>Default:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td><i>type</i> = <i>ZOLTAN_MEM_STAT_MAXIMUM</i></td>
</tr>
<td><b>Returned Value:</b></td>
<td></td>
<tr>
<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int </td>
<td>The number in bytes of the specific requested memory statistic.</td>
</tr>
<tr>
<td VALIGN=top><b>Example:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td> total = <b>Zoltan_Memory_Usage</b> (<i>ZOLTAN_MEM_STAT_TOTAL</i>);</td></tr>
</table>
<p>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Zoltan_Memory_Reset"></a>
<hr>
void <b>Zoltan_Memory_Reset</b>(int <i>type</i>);
<hr>
The <b>Zoltan_Memory_Reset</b> function sets the specified count to zero.
<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>type</i></td>
<td>Integer to specify the type of information to be reset .&nbsp These integers
are defined in <i>zoltan_mem.h</i>. Valid options include:
<blockquote>
ZOLTAN_MEM_STAT_TOTAL -- The function will set the count of total memory
allocated via Zoltan's memory allocation routines to zero.
<br>
ZOLTAN_MEM_STAT_MAXIMUM -- The function will set the count of maximum total memory
allocated via Zoltan's memory allocation routines back to zero.
</blockquote>
</td>
</tr>
<tr>
<td VALIGN=TOP><b>Default:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td><i>type</i> = <i>ZOLTAN_MEM_STAT_MAXIMUM</i></td>
</tr>
<tr>
<td VALIGN=top><b>Example:</b></td>
<td></td>
</tr>
<tr>
<td VALIGN=TOP></td>
<td> <b>Zoltan_Memory_Reset</b> (<i>ZOLTAN_MEM_STAT_TOTAL</i>);</td></tr>
</table>
<p>
<hr WIDTH="100%">
<br>[<a href="ug.html">Table of Contents</a>&nbsp; |&nbsp; <a href="ug_util_comm.html">Next:&nbsp;
Unstructured Communication Utilities</a>&nbsp; |&nbsp; <a href="ug_util.html">Previous:&nbsp;
Utilities</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>