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.
240 lines
12 KiB
240 lines
12 KiB
<!-------- @HEADER
|
|
!
|
|
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!
|
|
! Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
|
|
! Copyright 2012 Sandia Corporation
|
|
!
|
|
! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
|
|
! the U.S. Government retains certain rights in this software.
|
|
!
|
|
! Redistribution and use in source and binary forms, with or without
|
|
! modification, are permitted provided that the following conditions are
|
|
! met:
|
|
!
|
|
! 1. Redistributions of source code must retain the above copyright
|
|
! notice, this list of conditions and the following disclaimer.
|
|
!
|
|
! 2. Redistributions in binary form must reproduce the above copyright
|
|
! notice, this list of conditions and the following disclaimer in the
|
|
! documentation and/or other materials provided with the distribution.
|
|
!
|
|
! 3. Neither the name of the Corporation nor the names of the
|
|
! contributors may be used to endorse or promote products derived from
|
|
! this software without specific prior written permission.
|
|
!
|
|
! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
|
|
! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
|
|
! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
!
|
|
! Questions? Contact Karen Devine kddevin@sandia.gov
|
|
! Erik Boman egboman@sandia.gov
|
|
!
|
|
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!
|
|
! @HEADER
|
|
------->
|
|
|
|
<HTML>
|
|
<HEAD>
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
|
|
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
|
|
<META NAME="sandia.approved" CONTENT="SAND99-1376">
|
|
<META NAME="author" CONTENT="karen devine, kddevin@sandia.gov">
|
|
|
|
<TITLE> Zoltan Developer's Guide: FORTRAN Interface</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR="#FFFFFF">
|
|
|
|
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a> | <a href="dev_cpp.html">Next</a> | <a href="dev_mig.html">Previous</a></i></b></div>
|
|
|
|
|
|
<H2>
|
|
<A NAME="fortran dev"></A>FORTRAN Interface</H2>
|
|
With any change to the user API of Zoltan, the Fortran interface should
|
|
be modified to reflect the change. This section contains information about
|
|
the implementation of the Fortran interface which should cover most situations.
|
|
<UL><A HREF="#fortran dev structures">Structures</A>
|
|
<BR><A HREF="#fortran dev modifications">Modifications to an existing Zoltan
|
|
interface function</A>
|
|
<BR><A HREF="#fortran dev remove">Removing a Zoltan interface function</A>
|
|
<BR><A HREF="#fortran dev add">Adding a new Zoltan interface function</A>
|
|
<BR><A HREF="#fortran dev query">Query functions</A>
|
|
<BR><A HREF="#fortran dev enum">Enumerated types and defined constants</A></UL>
|
|
If you have questions or need assistance, contact <A HREF="mailto:william.mitchell@nist.gov">william.mitchell@nist.gov</A>.
|
|
|
|
<P>If changes are made to functions that are called by <I><A HREF="dev_driver.html#Zdrive">zdrive</A></I>,
|
|
then the changes should also be made to
|
|
<a href="dev_driver.html"><I>zfdrive</I></a>. Changes to the
|
|
Fortran interface can be tested by building and running <a href="dev_driver.html"><I>zfdrive</I></a>,
|
|
if the changes are in functions called by <a href="dev_driver.html"><I>zfdrive</I></a>.
|
|
The <a href="dev_driver.html"><I>zfdrive</I></a> program
|
|
works the same way as <I><A HREF="dev_driver.html">zdrive</A></I>
|
|
except that it is restricted to the
|
|
<a href="http://cs.sandia.gov/CRF/chac.html">Chaco</a>
|
|
examples and simpler input files.
|
|
|
|
<P>Any changes in the interface should also be reflected in the Fortran
|
|
API definitions in the <A HREF="../ug_html/ug.html">Zoltan User's Guide</A>.
|
|
<H3>
|
|
<A NAME="fortran dev structures"></A>Structures</H3>
|
|
All structures in the API have a corresponding user-defined type in the
|
|
Fortran interface. If a new structure is added, then modifications will
|
|
be required to <I>fort/fwrap.fpp</I> and <I>fort/cwrap.c</I>. In these
|
|
files, search for <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>
|
|
and "do like it does."
|
|
|
|
<P>An explanation of how structures are handled may help. The Fortran user-defined
|
|
type for the structure simply contains the address of the structure, i.e.,
|
|
the C pointer returned by a call to create the structure. Note that the
|
|
user does not have access to the components of the structure, and can only
|
|
pass the structure to functions. Within the Fortran structure, the
|
|
address is stored in a variable of type(<B>Zoltan_PTR</B>), which is a character
|
|
string containing one character for each byte of the address. This gives
|
|
the best guarantee of portability under the Fortran and C standards. Also,
|
|
to insure portability of passing character strings, the character string
|
|
is converted to an array of integers before passing it between Fortran
|
|
and C. The process of doing this is most easily seen by looking at <B><A HREF="../ug_html/ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</A></B>,
|
|
which has little else to clutter the code.
|
|
<H3>
|
|
<A NAME="fortran dev modifications"></A>Modifications to an existing Zoltan
|
|
interface function</H3>
|
|
If the argument list or return type of a user-callable function in Zoltan
|
|
changes, the same changes must be made in the Fortran interface routines.
|
|
This involves changes in two files: <I>fort/fwrap.fpp</I> and <I>fort/cwrap.c</I>.
|
|
In these files, search for the function name with the prefix <B>Zoltan_ </B>omitted,
|
|
and modify the argument list, argument declarations, return type, and call
|
|
to the C library function as appropriate. When adding a new argument, if
|
|
there is not already an argument of the same type, look at another
|
|
function that does have an argument of that type for guidance.
|
|
<H3>
|
|
<A NAME="fortran dev remove"></A>Removing a Zoltan interface function</H3>
|
|
If a user callable function is removed from the Zoltan library, edit <I>fort/fwrap.fpp</I>
|
|
and <I>fort/cwrap.c</I> to remove all references to that function.
|
|
<H3>
|
|
<A NAME="fortran dev add"></A>Adding a new Zoltan interface function</H3>
|
|
Adding a new function involves changes to the two files <I>fort/fwrap.fpp</I>
|
|
and <I>fort/cwrap.c</I>. Perhaps the easiest way to add a new function
|
|
to these files is to pick some existing function, search for all occurrences
|
|
of it, and use that code as a guide for the implementation of the interface
|
|
for the new function. <B><A HREF="../ug_html/ug_interface_augment.html#Zoltan_LB_Point_Assign">Zoltan_LB_Point_Assign</A></B>
|
|
is a nice minimal function to use as an example. Use a case insensitive
|
|
search on the name of the function without the <B>Zoltan_LB_</B> prefix, for example
|
|
<B>point_assign</B>.
|
|
|
|
<P>Here are the items in <I>fwrap.fpp</I>:
|
|
<UL>
|
|
<LI>
|
|
public statement: The name of the function should be included in the list
|
|
of public entities.</LI>
|
|
|
|
<LI>
|
|
interface for the C wrapper: Copy one of these and modify the function
|
|
name, argument list and declarations for the new function. The name is
|
|
of the form <B>Zfw_LB_Point_Assign</B> (fw stands for Fortran wrapper).</LI>
|
|
|
|
<LI>
|
|
generic interface: This assigns the function name to be a generic name
|
|
for one or more module procedures.</LI>
|
|
|
|
<LI>
|
|
module procedure(s): These are the Fortran-side wrapper functions. Usually
|
|
there is one module procedure of the form <B>Zf90_LB_Point_Assign</B>. If
|
|
one argument can have more than one type passed to it (for example, it
|
|
is type void in the C interface), then there must be one module procedure
|
|
for each type that can be passed. These are distinguished by appending
|
|
a digit to the end of the module procedure name. If n arguments can have
|
|
more than one type, then n digits are appended. See <B><A HREF="../ug_html/ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</A></B>
|
|
for example. Generally the module procedure just calls the C-side wrapper
|
|
function,<B> </B>but in some cases it may need to coerce data to a different
|
|
type (e.g., <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>),
|
|
or may actually do real work (e.g., <B><A HREF="../ug_html/ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</A></B>).</LI>
|
|
|
|
<BR> </UL>
|
|
Here are the items in <I>cwrap.c</I>:
|
|
<UL>
|
|
<LI>
|
|
name mangling: These are macros to convert the function name from the case
|
|
sensitive C name (for example, <B>Zfw_LB_Point_Assign</B>) to the mangled
|
|
name produced by the Fortran compiler. There are four of these for each
|
|
function:</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
lowercase (<B>zfw_lb_point_assign</B>),</LI>
|
|
|
|
<LI>
|
|
uppercase (<B>ZFW_LB_POINT_ASSIGN</B>),</LI>
|
|
|
|
<LI>
|
|
lowercase with underscore (<B>zfw_lb_point_assign_</B>), and</LI>
|
|
|
|
<LI>
|
|
lower case with double underscore (<B>zfw_point_assign__</B> but the
|
|
second underscore is appended only if the name already contains an underscore,
|
|
which will always be the case for names starting with <B>Zfw_</B>).</LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
C-side wrapper function: Usually this just calls the Zoltan library function
|
|
after coercing the form of the data (for example, constructing the pointer
|
|
to <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A> </B>and call-by-reference
|
|
to call-by-value conversions).</LI>
|
|
</UL>
|
|
|
|
<H3>
|
|
<A NAME="fortran dev query"></A>Query functions</H3>
|
|
If a query function is added, deleted or changed, modifications must be
|
|
made to <I>fort/fwrap.fpp</I> and <I>fort/cwrap.c</I>, similar to the modifications
|
|
for interface functions, and possibly also<I> include/zoltan.h</I> and <I>zz/zz_const.h</I>.
|
|
|
|
<P>Here are the places query functions appear in <I>fwrap.fpp</I>:
|
|
<UL>
|
|
<LI>
|
|
public statement for the <B><A HREF="dev_lb_interface.html#interface_fns">ZOLTAN_FN_TYPE</A></B>
|
|
argument: These are identical to the C enumerated type.</LI>
|
|
|
|
<LI>
|
|
definition of the <B><A HREF="dev_lb_interface.html#interface_fns">ZOLTAN_FN_TYPE</A></B>
|
|
arguments: There are two groups of these, one containing subroutines (void
|
|
functions) and one containing functions (int functions). Put the new symbol
|
|
in the right category. The value assigned to the new symbol must agree
|
|
exactly with where the symbol appears in the order of the enumerated type.</LI>
|
|
</UL>
|
|
Here are the places query functions appear in <I>cwrap.c</I>:
|
|
<UL>
|
|
<LI>
|
|
reverse wrappers: These are the query functions that are actually called
|
|
by the Zoltan library routines when the query function was registered from
|
|
Fortran. They are just wrappers to call the registered Fortran routine,
|
|
coercing argument types as necessary. Look at <B>Zoltan_Num_Edges_Fort_Wrapper</B>
|
|
for an example.</LI>
|
|
|
|
<LI>
|
|
<B>Zfw_Set_Fn</B>: This has a switch based on the value of the <B><A HREF="dev_lb_interface.html#interface_fns">ZOLTAN_FN_TYPE</A></B>
|
|
argument to set the Fortran query function and wrapper in the <B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>.</LI>
|
|
</UL>
|
|
In <I>zz/zz_const.h</I>, if a new field is added to the structures for
|
|
a new query function, it should be added in both C and Fortran forms. In
|
|
<I>include/zoltan.h</I>, if a new typedef for a query function is added,
|
|
it should be added in both C and Fortran forms. See these files for examples.
|
|
<H3>
|
|
<A NAME="fortran dev enum"></A>Enumerated types and defined constants</H3>
|
|
Enumerated types and defined constants that the application uses as the
|
|
value for an arguments must be placed in<I> fwrap.fpp</I> with the same
|
|
value. See <B><A HREF="../ug_html/ug_interface.html#Error Codes">ZOLTAN_OK</A></B>
|
|
for an example.
|
|
<HR WIDTH="100%">
|
|
<BR>[<A HREF="dev.html">Table of Contents</A> | <A HREF="dev_cpp.html">Next:
|
|
C++ Interface</A> | <A HREF="dev_mig.html">Previous:
|
|
Migration Tools</A> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
|
|
</BODY>
|
|
</HTML>
|
|
|