You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
822 lines
27 KiB
822 lines
27 KiB
<!-------- @HEADER
|
|
!
|
|
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!
|
|
! Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
|
|
! Copyright 2012 Sandia Corporation
|
|
!
|
|
! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
|
|
! the U.S. Government retains certain rights in this software.
|
|
!
|
|
! Redistribution and use in source and binary forms, with or without
|
|
! modification, are permitted provided that the following conditions are
|
|
! met:
|
|
!
|
|
! 1. Redistributions of source code must retain the above copyright
|
|
! notice, this list of conditions and the following disclaimer.
|
|
!
|
|
! 2. Redistributions in binary form must reproduce the above copyright
|
|
! notice, this list of conditions and the following disclaimer in the
|
|
! documentation and/or other materials provided with the distribution.
|
|
!
|
|
! 3. Neither the name of the Corporation nor the names of the
|
|
! contributors may be used to endorse or promote products derived from
|
|
! this software without specific prior written permission.
|
|
!
|
|
! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
|
|
! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
|
|
! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
!
|
|
! Questions? Contact Karen Devine kddevin@sandia.gov
|
|
! Erik Boman egboman@sandia.gov
|
|
!
|
|
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!
|
|
! @HEADER
|
|
------->
|
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Mozilla/4.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>
|
|
| <a href="ug_interface_lb.html">Next</a> | <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_<<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> int <i>argc</i>,
|
|
<br> char **<i>argv</i>,
|
|
<br> 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>)
|
|
<br>INTEGER(Zoltan_INT) :: Zoltan_Initialize
|
|
<br>INTEGER(Zoltan_INT), INTENT(IN), OPTIONAL :: argc
|
|
<br>CHARACTER(LEN=*), DIMENSION(*), INTENT(IN), OPTIONAL :: argv
|
|
<br>REAL(Zoltan_FLOAT), INTENT(OUT) :: ver </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, 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. 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>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> argc</i></td>
|
|
|
|
<td>The number of command-line arguments to the application.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> argv</i></td>
|
|
|
|
<td>An array of strings containing the command-line arguments to the application.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> 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> 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> 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>)
|
|
<br>TYPE(Zoltan_Struct), pointer :: Zoltan_Create
|
|
<br>INTEGER, INTENT(IN) :: communicator </td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP WIDTH="15%" NOSAVE>C++:</td>
|
|
<td WIDTH="85%"><b>Zoltan</b> (
|
|
<br> 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>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> 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: </b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> 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> <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>)
|
|
<br>TYPE(Zoltan_Struct), pointer :: Zoltan_Copy
|
|
<br>TYPE(Zoltan_Struct), INTENT(IN) :: from </td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP WIDTH="15%" NOSAVE>C++:</td>
|
|
<td WIDTH="85%"><b>Zoltan</b> (
|
|
<br> 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>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> from</i></td>
|
|
|
|
<td>A pointer to the <b>Zoltan_Struct</b> that is to be copied.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value: </b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> 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> <b>Zoltan_Struct</b> *<i>to</i>,
|
|
<br> <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>)
|
|
<br>INTEGER(Zoltan_INT) :: Zoltan_Copy_To
|
|
<br>TYPE(Zoltan_Struct), INTENT(IN) :: to
|
|
<br>TYPE(Zoltan_Struct), INTENT(IN) :: from </td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP WIDTH="15%" NOSAVE>C++:</td>
|
|
<td WIDTH="85%"><b>Zoltan</b> & operator= (
|
|
<br> 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>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> 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> 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: </b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> 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> struct <b>Zoltan_Struct</b> *<i>zz</i>,
|
|
<br> char *<i>param_name</i>,
|
|
<br> 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>)
|
|
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_Param
|
|
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz
|
|
<br>CHARACTER(LEN=*), INTENT(IN) :: param_name, new_value </td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP NOSAVE>C++:</td>
|
|
|
|
<td WIDTH="85%">int <b>Zoltan::Set_Param</b> (
|
|
<br> const std::string &<b>param_name</b>,
|
|
<br> 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. All Zoltan parameters have
|
|
reasonable default values, but this routine allows a user to provide alternative
|
|
values if desired.
|
|
<br>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i> 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> param_name</i></td>
|
|
|
|
<td>A string containing the name of the parameter to be altered.
|
|
Note that the string is case-insensitive. Also, different Zoltan
|
|
structures can have different parameter values. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> new_val</i></td>
|
|
|
|
<td>A string containing the new value for the parameter. Example
|
|
strings include "3.154", "True", "7" or anything appropriate for the parameter
|
|
being set. As above, the string is case-insensitive. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> 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> struct <b>Zoltan_Struct</b> *<i>zz</i>,
|
|
<br> char *<i>param_name</i>,
|
|
<br> char *<i>new_val</i>,
|
|
<br> 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> const std::string &<i>param_name</i>,
|
|
<br> const std::string &<i>new_val</i>,
|
|
<br> 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>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i> 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> param_name</i></td>
|
|
|
|
<td>A string containing the name of the parameter to be altered.
|
|
Note that the string is case-insensitive. Also, different Zoltan
|
|
structures can have different parameter values. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> new_val</i></td>
|
|
|
|
<td>A string containing the new value for the parameter. Example
|
|
strings include "3.154", "True", "7" or anything appropriate for the parameter
|
|
being set. As above, the string is case-insensitive. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> 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> 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> struct <b>Zoltan_Struct *</b><i>zz</i>,
|
|
<br> <b>ZOLTAN_FN_TYPE </b><i>fn_type</i>,
|
|
<br> void (*<i>fn_ptr</i>)(),
|
|
<br> 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>)
|
|
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_Fn
|
|
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz
|
|
<br>TYPE(ZOLTAN_FN_TYPE), INTENT(IN) :: fn_type
|
|
<br>EXTERNAL :: fn_ptr
|
|
<br><<i>type-data</i>>, OPTIONAL :: data
|
|
<p><<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. </td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP NOSAVE>C++:</td>
|
|
|
|
<td WIDTH="85%">int <b>Zoltan::Set_Fn</b> (
|
|
<br> const <b>ZOLTAN_FN_TYPE </b> &<i>fn_type</i>,
|
|
<br> void (*<i>fn_ptr</i>)(),
|
|
<br> 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>. 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_<<i>zoltan_fn_type</i>>_Fn</a></b>.
|
|
<br>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> 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> 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> fn_ptr</i></td>
|
|
|
|
<td>A pointer to the application-supplied query function being registered.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> 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> 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_<<i>zoltan_fn_type</i>>_Fn</b> (
|
|
<br> struct <b>Zoltan_Struct </b>*<i>zz</i>,
|
|
<br> <<b><i><a href="ug_query.html">zoltan_fn_type</a></i></b>>
|
|
(*<i>fn_ptr</i>)(),
|
|
<br> void *<i>data</i>);</td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
|
|
|
|
<td>FUNCTION <b>Zoltan_Set_<<i>zoltan_fn_type</i>>_Fn</b>(<i>zz, fn_ptr,
|
|
data</i>)
|
|
<br>INTEGER(Zoltan_INT) :: Zoltan_Set_<<i><a href="ug_query.html">zoltan_fn_type</a></i>>_Fn
|
|
<br>TYPE(Zoltan_Struct), INTENT(IN) :: zz
|
|
<br>EXTERNAL :: fn_ptr
|
|
<br><<i>type-data</i>>, OPTIONAL :: data
|
|
<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><<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. </td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP NOSAVE>C++:</td>
|
|
|
|
<td WIDTH="85%">int <b>Zoltan::Set_<<i>zoltan_fn_type</i>>_Fn</b> (
|
|
<br> <<b><i><a href="ug_query.html">zoltan_fn_type</a></i></b>>
|
|
(*<i>fn_ptr</i>)(),
|
|
<br> void *<i>data</i> = 0);</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<hr WIDTH="100%">The interface functions <b>Zoltan_Set_<<i>zoltan_fn_type</i>>_Fn</b>,
|
|
where <b><<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. 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>.
|
|
Each query function has an associated <b>Zoltan_Set_<<i>zoltan_fn_type</i>>_Fn</b>.
|
|
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_<<i>zoltan_fn_type</i>>_Fn</b>.
|
|
<br><b>Zoltan_Set_<<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_<<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> 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> fn_ptr</i></td>
|
|
|
|
<td>A pointer to the application-supplied query function being registered.
|
|
The type of the pointer matches <<b><i><a href="ug_query.html">zoltan_fn_type</a></i></b>>
|
|
in the name <b>Zoltan_Set_<<i>zoltan_fn_type</i>>_Fn</b>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> 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> 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> 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>
|
|
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> 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>)
|
|
<br>TYPE(Zoltan_Struct), POINTER :: zz </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>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> 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. </td>
|
|
</tr>
|
|
</table>
|
|
<!------------------------------------------------------------------------->
|
|
<p>
|
|
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a> | <a href="ug_interface_lb.html">Next:
|
|
Load-Balancing Functions</a> | <a href="ug_interface.html">Previous:
|
|
Zoltan Interface Functions</a> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
|
|
</body>
|
|
</html>
|
|
|