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.
377 lines
18 KiB
377 lines
18 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.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> | <a href="ug_interface.html">Next</a> | <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<path to the installation include directory></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>
|
|
<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>
|
|
<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) </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>
|
|
<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>,
|
|
the Fortran interface uses arrays of integers, as unsigned integers are
|
|
not available in Fortran. Thus, each ID is represented as an array
|
|
(possibly of size 1) of integers. 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 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:
|
|
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> |
|
|
<A HREF="ug_interface.html">Next: Zoltan Interface Functions</A>
|
|
| <A HREF="ug_cpp.html">Previous: C++ Interface</A> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
|
|
</BODY>
|
|
</HTML>
|
|
|