lib
/
EXODUS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Cloned SEACAS for EXODUS library with extra build files for internal package management.
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.
3 Commits
1 Branch
0 Tags
19 MiB
Tag: Branch: Tree: ec572c6da6
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'ec572c6da6'
${ noResults }
EXODUS/packages/zoltan/docs/ug_html/ug_fortran.html

378 lines
18 KiB
Raw Normal View History Unescape

Initial commit
2 years ago
<!-------- @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>