diff options
Diffstat (limited to 'doc/f2py/python9.tex')
| -rw-r--r-- | doc/f2py/python9.tex | 1044 |
1 files changed, 0 insertions, 1044 deletions
diff --git a/doc/f2py/python9.tex b/doc/f2py/python9.tex deleted file mode 100644 index 524d61113..000000000 --- a/doc/f2py/python9.tex +++ /dev/null @@ -1,1044 +0,0 @@ -\documentclass[twocolumn]{article} -\usepackage{epsfig} -\usepackage{xspace} -\usepackage{verbatim} - - -\headsep=0pt -\topmargin=0pt -\headheight=0pt -\oddsidemargin=0pt -\textwidth=6.5in -\textheight=9in -%%tth:\newcommand{\xspace}{ } -\newcommand{\fpy}{\texttt{f2py}\xspace} -\newcommand{\bs}{\symbol{`\\}} -% need bs here: -%%tth:\newcommand{\bs}{\texttt{<backslash>}} - -\newcommand{\tthhide}[1]{#1} -\newcommand{\latexhide}[1]{} -%%tth:\newcommand{\tthhide}[1]{} -%%tth:\newcommand{\latexhide}[1]{#1} - -\newcommand{\shell}[1]{ -\latexhide{ - \special{html: -<BLOCKQUOTE> -<pre> -sh> #1 -</pre> -</BLOCKQUOTE>} -} -\tthhide{ - \\[1ex] - \hspace*{1em} - \texttt{sh> \begin{minipage}[t]{0.8\textwidth}#1\end{minipage}}\\[1ex] -} -} - -\newcommand{\email}[1]{\special{html:<A href="mailto:#1">}\texttt{<#1>}\special{html:</A>}} -\newcommand{\wwwsite}[1]{\special{html:<A href="#1">}{#1}\special{html:</A>}} -\title{Fortran to Python Interface Generator with -an Application to Aerospace Engineering} -\author{ -\large Pearu Peterson\\ -\small \email{pearu@cens.ioc.ee}\\ -\small Center of Nonlinear Studies\\ -\small Institute of Cybernetics at TTU\\ -\small Akadeemia Rd 21, 12618 Tallinn, ESTONIA\\[2ex] -\large Joaquim R. R. A. Martins and Juan J. Alonso\\ -\small \email{joaquim.martins@stanford.edu}, \email{jjalonso@stanford.edu}\\ -\small Department of Aeronautics and Astronautics\\ -\small Stanford University, CA -} -\date{$Revision: 1.17 $\\\today} -\begin{document} - -\maketitle - -\special{html: Other formats of this document: -<A href=f2python9.ps.gz>Gzipped PS</A>, -<A href=f2python9.pdf>PDF</A> -} - -\begin{abstract} - FPIG --- Fortran to Python Interface Generator --- is a tool for - generating Python C/API extension modules that interface - Fortran~77/90/95 codes with Python. This tool automates the process - of interface generation by scanning the Fortran source code to - determine the signatures of Fortran routines and creating a - Python C/API module that contains the corresponding interface - functions. FPIG also attempts to find dependence relations between - the arguments of a Fortran routine call (e.g. an array and its - dimensions) and constructs interface functions with potentially - fewer arguments. The tool is extremely flexible since the user has - control over the generation process of the interface by specifying the - desired function signatures. The home page for FPIG can be found at - \wwwsite{http://cens.ioc.ee/projects/f2py2e/}. - - FPIG has been used successfully to wrap a large number of Fortran - programs and libraries. Advances in computational science have led - to large improvements in the modeling of physical systems which are - often a result of the coupling of a variety of physical models that - were typically run in isolation. Since a majority of the available - physical models have been previously written in Fortran, the - importance of FPIG in accomplishing these couplings cannot be - understated. In this paper, we present an application of FPIG to - create an object-oriented framework for aero-structural analysis and - design of aircraft. -\end{abstract} - -%%tth: -\tableofcontents - -\section{Preface} -\label{sec:preface} - -The use of high-performance computing has made it possible to tackle -many important problems and discover new physical phenomena in science -and engineering. These accomplishments would not have been achieved -without the computer's ability to process large amounts of data in a -reasonably short time. It can safely be said that the computer has -become an essential tool for scientists and engineers. However, the -diversity of problems in science and engineering has left its mark as -computer programs have been developed in different programming -languages, including languages developed to describe certain specific -classes of problems. - -In interdisciplinary fields it is not uncommon for scientists and -engineers to face problems that have already been solved in a -different programming environment from the one they are familiar with. -Unfortunately, researchers may not have the time or willingness to -learn a new programming language and typically end up developing the -corresponding tools in the language that they normally use. This -approach to the development of new software can substantially impact -the time to develop and the quality of the resulting product: firstly, -it usually takes longer to develop and test a new tool than to learn a -new programming environment, and secondly it is very unlikely that a -non-specialist in a given field can produce a program that is more -efficient than more established tools. - -To avoid situations such as the one described above, one alternative -would be to provide automatic or semi-automatic interfaces between programming -languages. Another possibility would be to provide language -translators, but these obviously require more work than interface -generators --- a translator must understand all language constructs -while an interface generator only needs to understand a subset of these -constructs. With an automatic interface between two languages, scientists or -engineers can effectively use programs written in other programming -languages without ever having to learn them. - -Although it is clear that it is impossible to interface arbitrary programming -languages with each other, there is no reason for doing so. Low-level languages such as C and Fortran are well known for -their speed and are therefore suitable for applications where -performance is critical. High-level scripting languages, on the other -hand, are generally slower but much easier to learn and use, -especially when performing interactive analysis. Therefore, it makes -sense to create interfaces only in one direction: from lower-level -languages to higher-level languages. - -In an ideal world, scientists and engineers would use higher-level -languages for the manipulation of the mathematical formulas in a problem -rather than having to struggle with tedious programming details. For tasks -that are computationally demanding, they would use interfaces to -high-performance routines that are written in a lower-level language -optimized for execution speed. - - -\section{Introduction} -\label{sec:intro} - -This paper presents a tool that has been developed for the creation of -interfaces between Fortran and Python. - - -The Fortran language is popular in -scientific computing, and is used mostly in applications that use -extensive matrix manipulations (e.g. linear algebra). Since Fortran - has been the standard language among scientists and engineers for - at least three decades, there is a large number of legacy codes available that - perform a variety of tasks using very sophisticated algorithms (see -e.g. \cite{netlib}). - -The Python language \cite{python}, on the other hand, is a relatively -new programming language. It is a very high-level scripting language -that supports object-oriented programming. What makes Python -especially appealing is its very clear and natural syntax, which makes it -easy to learn and use. With Python one can implement relatively -complicated algorithms and tasks in a short time with very compact -source code. - -Although there are ongoing projects for extending Python's usage in -scientific computation, it lacks reliable tools that are common in -scientific and engineering such as ODE integrators, equation solvers, -tools for FEM, etc. The implementation of all of these tools in Python -would be not only too time-consuming but also inefficient. On the -other hand, these tools are already developed in other, -computationally more efficient languages such as Fortran or C. -Therefore, the perfect role for Python in the context of scientific -computing would be that of a ``gluing'' language. That is, the role -of providing high-level interfaces to C, C++ and Fortran libraries. - -There are a number of widely-used tools that can be used for interfacing -software libraries to Python. For binding C libraries with various -scripting languages, including Python, the tool most often used is -SWIG \cite{swig}. Wrapping Fortran routines with Python is less -popular, mainly because there are many platform and compiler-specific -issues that need to be addressed. Nevertheless, there is great -interest in interfacing Fortran libraries because they provide -invaluable tools for scientific computing. At LLNL, for example, a tool -called PyFort has been developed for connecting Fortran and -Python~\cite{pyfort}. - -The tools mentioned above require an input file describing signatures -of functions to be interfaced. To create these input files, one needs -to have a good knowledge of either C or Fortran. In addition, -binding libraries that have thousands of routines can certainly constitute a -very tedious task, even with these tools. - -The tool that is introduced in this paper, FPIG (Fortran to Python -Interface Generator)~\cite{fpig}, automatically generates interfaces -between Fortran and Python. It is different from the tools mentioned -above in that FPIG can create signature files automatically by -scanning the source code of the libraries and then construct Python -C/API extension modules. Note that the user need not be experienced -in C or even Fortran. In addition, FPIG is designed to wrap large -Fortran libraries containing many routines with only one or two -commands. This process is very flexible since one can always modify -the generated signature files to insert additional attributes in order -to achieve more sophisticated interface functions such as taking care -of optional arguments, predicting the sizes of array arguments and -performing various checks on the correctness of the input arguments. - -The organization of this paper is as follows. First, a simple example -of FPIG usage is given. Then FPIG's basic features are described and -solutions to platform and compiler specific issues are discussed. -Unsolved problems and future work on FPIG's development are also -addressed. Finally, an application to a large aero-structural solver -is presented as real-world example of FPIG's usage. - -\section{Getting Started} -\label{sec:getstart} - -To get acquainted with FPIG, let us consider the simple Fortran~77 -subroutine shown in Fig. \ref{fig:exp1.f}. -\begin{figure}[htb] - \latexhide{\label{fig:exp1.f}} - \special{html:<BLOCKQUOTE>} - \verbatiminput{examples/exp1.f} - \special{html:</BLOCKQUOTE>} - \caption{Example Fortran code \texttt{exp1.f}. This routine calculates - the simplest rational lower and upper approximations to $e$ (for - details of - the algorithm see \cite{graham-etal}, p.122)} - \tthhide{\label{fig:exp1.f}} -\end{figure} -In the sections that follow, two ways of creating interfaces to this -Fortran subroutine are described. The first and simplest way is -suitable for Fortran codes that are developed in connection with \fpy. -The second and not much more difficult method, is suitable for -interfacing existing Fortran libraries which might have been developed -by other programmers. - -Numerical Python~\cite{numpy} is needed in order to compile extension -modules generated by FPIG. - -\subsection{Interfacing Simple Routines} -\label{sec:example1} - -In order to call the Fortran routine \texttt{exp1} from Python, let us -create an interface to it by using \fpy (FPIG's front-end program). In -order to do this, we issue the following command, \shell{f2py -m foo -exp1.f} where the option \texttt{-m foo} sets the name of the Python -C/API extension module that \fpy will create to -\texttt{foo}. To learn more about the \fpy command line options, run \fpy -without arguments. - -The output messages in Fig. \ref{fig:f2pyoutmess} -illustrate the procedure followed by \fpy: - (i) it scans the Fortran source code specified in the command line, - (ii) it analyses and determines the routine signatures, - (iii) it constructs the corresponding Python C/API extension modules, - (iv) it writes documentation to a LaTeX file, and - (v) it creates a GNU Makefile for building the shared modules. -\begin{figure}[htb] - \latexhide{\label{fig:f2pyoutmess}} - \special{html:<BLOCKQUOTE>} - {\tthhide{\small} - \verbatiminput{examples/exp1mess.txt} - } - \special{html:</BLOCKQUOTE>} - \caption{Output messages of \texttt{f2py -m foo exp1.f}.} - \tthhide{\label{fig:f2pyoutmess}} -\end{figure} - -Now we can build the \texttt{foo} module: -\shell{make -f Makefile-foo} - -Figure \ref{fig:exp1session} illustrates a sample session for - calling the Fortran routine \texttt{exp1} from Python. -\begin{figure}[htb] - \latexhide{\label{fig:exp1session}} - \special{html:<BLOCKQUOTE>} - \verbatiminput{examples/exp1session.txt} - \special{html:</BLOCKQUOTE>} - \caption{Calling Fortran routine \texttt{exp1} from Python. Here - \texttt{l[0]/l[1]} gives an estimate to $e$ with absolute error - less than \texttt{u[0]/u[1]-l[0]/l[1]} (this value may depend on - the platform and compiler used).} - \tthhide{\label{fig:exp1session}} -\end{figure} - -Note the difference between the signatures of the Fortran routine -\texttt{exp1(l,u,n)} and the corresponding wrapper function -\texttt{l,u=exp1([n])}. Clearly, the later is more informative to -the user: \texttt{exp1} takes one optional argument \texttt{n} and it -returns \texttt{l}, \texttt{u}. This exchange of signatures is -achieved by special comment lines (starting with \texttt{Cf2py}) in -the Fortran source code --- these lines are interpreted by \fpy as -normal Fortran code. Therefore, in the given example the line \texttt{Cf2py - integer*4 :: n = 1} informs \fpy that the variable \texttt{n} is -optional with a default value equal to one. The line \texttt{Cf2py - intent(out) l,u} informs \fpy that the variables \texttt{l,u} are to be -returned to Python after calling Fortran function \texttt{exp1}. - -\subsection{Interfacing Libraries} -\label{sec:example2} - -In our example the Fortran source \texttt{exp1.f} contains \fpy -specific information, though only as comments. When interfacing -libraries from other parties, it is not recommended to modify their -source. Instead, one should use a special auxiliary file to collect -the signatures of all Fortran routines and insert \fpy specific -declaration and attribute statements in that file. This auxiliary file -is called a \emph{signature file} and is identified by the extension -\texttt{.pyf}. - -We can use \fpy to generate these signature files by using the -\texttt{-h <filename>.pyf} option. -In our example, \fpy could have been called as follows, -\shell{f2py -m foo -h foo.pyf exp1.f} -where the option \texttt{-h foo.pyf} requests \fpy to read the -routine signatures, save them to the file \texttt{foo.pyf}, and then -exit. -If \texttt{exp1.f} in Fig.~\ref{fig:exp1.f} were to -contain no lines starting with \texttt{Cf2py}, the corresponding -signature file \texttt{foo.pyf} would be as shown in Fig.~\ref{fig:foo.pyf}. -In order to obtain the exchanged and more convenient signature -\texttt{l,u=foo.exp1([n])}, we would edit \texttt{foo.pyf} as shown in -Fig.~\ref{fig:foom.pyf}. -The Python C/API extension module \texttt{foo} can be constructed by -applying \fpy to the signature file with the following command: -\shell{f2py foo.pyf} -The procedure for building the corresponding shared module and using -it in Python is identical to the one described in the previous section. - -\begin{figure}[htb] - \latexhide{\label{fig:foo.pyf}} - \special{html:<BLOCKQUOTE>} - \verbatiminput{examples/foo.pyf} - \special{html:</BLOCKQUOTE>} - \caption{Raw signature file \texttt{foo.pyf} generated with - \texttt{f2py -m foo -h foo.pyf exp1.f}} - \tthhide{\label{fig:foo.pyf}} -\end{figure} -\begin{figure}[htb] - \latexhide{\label{fig:foom.pyf}} - \special{html:<BLOCKQUOTE>} - \verbatiminput{examples/foom.pyf} - \special{html:</BLOCKQUOTE>} - \caption{Modified signature file \texttt{foo.pyf}} - \tthhide{\label{fig:foom.pyf}} -\end{figure} - -As we can see, the syntax of the signature file is an -extension of the Fortran~90/95 syntax. This means that only a few new -constructs are introduced for \fpy in addition to all standard Fortran -constructs; signature files can even be written in fixed form. A -complete set of constructs that are used when creating interfaces, is -described in the \fpy User's Guide \cite{f2py-ug}. - - -\section{Basic Features} -\label{sec:features} - -In this section a short overview of \fpy features is given. -\begin{enumerate} -\item All basic Fortran types are supported. They include -the following type specifications: -\begin{verbatim} -integer[ | *1 | *2 | *4 | *8 ] -logical[ | *1 | *2 | *4 | *8 ] -real[ | *4 | *8 | *16 ] -complex[ | *8 | *16 | *32 ] -double precision, double complex -character[ |*(*)|*1|*2|*3|...] -\end{verbatim} -In addition, they can all be in the kind-selector form -(e.g. \texttt{real(kind=8)}) or char-selector form -(e.g. \texttt{character(len=5)}). -\item Arrays of all basic types are supported. Dimension - specifications can be of form \texttt{<dimension>} or - \texttt{<start>:<end>}. In addition, \texttt{*} and \texttt{:} - dimension specifications can be used for input arrays. - Dimension specifications may contain also \texttt{PARAMETER}'s. -\item The following attributes are supported: - \begin{itemize} - \item - \texttt{intent(in)}: used for input-only arguments. - \item - \texttt{intent(inout)}: used for arguments that are changed in - place. - \item - \texttt{intent(out)}: used for return arguments. - \item - \texttt{intent(hide)}: used for arguments to be removed from - the signature of the Python function. - \item - \texttt{intent(in,out)}, \texttt{intent(inout,out)}: used for - arguments with combined behavior. - \item - \texttt{dimension(<dimspec>)} - \item - \texttt{depend([<names>])}: used - for arguments that depend on other arguments in \texttt{<names>}. - \item - \texttt{check([<C booleanexpr>])}: used for checking the - correctness of input arguments. - \item - \texttt{note(<LaTeX text>)}: used for - adding notes to the module documentation. - \item - \texttt{optional}, \texttt{required} - \item - \texttt{external}: used for call-back arguments. - \item - \texttt{allocatable}: used for Fortran 90/95 allocatable arrays. - \end{itemize} -\item Using \fpy one can call arbitrary Fortran~77/90/95 subroutines - and functions from Python, including Fortran 90/95 module routines. -\item Using \fpy one can access data in Fortran~77 COMMON blocks and - variables in Fortran 90/95 modules, including allocatable arrays. -\item Using \fpy one can call Python functions from Fortran (call-back - functions). \fpy supports very flexible hooks for call-back functions. -\item Wrapper functions perform the necessary type conversations for their - arguments resulting in contiguous Numeric arrays that are suitable for - passing to Fortran routines. -\item \fpy generates documentation strings -for \texttt{\_\_doc\_\_} attributes of the wrapper functions automatically. -\item \fpy scans Fortran codes and creates the signature - files. It automatically detects the signatures of call-back functions, - solves argument dependencies, decides the order of initialization of - optional arguments, etc. -\item \fpy automatically generates GNU Makefiles for compiling Fortran - and C codes, and linking them to a shared module. - \fpy detects available Fortran and C compilers. The - supported compilers include the GNU project C Compiler (gcc), Compaq - Fortran, VAST/f90 Fortran, Absoft F77/F90, and MIPSpro 7 Compilers, etc. - \fpy has been tested to work on the following platforms: Intel/Alpha - Linux, HP-UX, IRIX64. -\item Finally, the complete \fpy User's Guide is available in various - formats (ps, pdf, html, dvi). A mailing list, - \email{f2py-users@cens.ioc.ee}, is open for support and feedback. See - the FPIG's home page for more information \cite{fpig}. -\end{enumerate} - - -\section{Implementation Issues} -\label{sec:impl} - -The Fortran to Python interface can be thought of as a three layer -``sandwich'' of different languages: Python, C, and Fortran. This -arrangement has two interfaces: Python-C and C-Fortran. Since Python -itself is written in C, there are no basic difficulties in -implementing the Python-C interface~\cite{python-doc:ext}. The C-Fortran -interface, on the other hand, results in many platform and compiler specific -issues that have to be dealt with. We will now discuss these issues -in some detail and describe how they are solved in FPIG. - -\subsection{Mapping Fortran Types to C Types} -\label{sec:mapF2Ctypes} - -Table \ref{tab:mapf2c} defines how Fortran types are mapped to C types -in \fpy. -\begin{table}[htb] - \begin{center} - \begin{tabular}[c]{l|l} - Fortran type & C type \\\hline - \texttt{integer *1} & \texttt{char}\\ - \texttt{byte} & \texttt{char}\\ - \texttt{integer *2} & \texttt{short}\\ - \texttt{integer[ | *4]} & \texttt{int}\\ - \texttt{integer *8} & \texttt{long long}\\ - \texttt{logical *1} & \texttt{char}\\ - \texttt{logical *2} & \texttt{short}\\ - \texttt{logical[ | *4]} & \texttt{int}\\ - \texttt{logical *8} & \texttt{int}\\ - \texttt{real[ | *4]} & \texttt{float}\\ - \texttt{real *8} & \texttt{double}\\ - \texttt{real *16} & \texttt{long double}\\ - \texttt{complex[ | *8]} & \texttt{struct \{float r,i;\}}\\ - \texttt{complex *16} & \texttt{struct \{double r,i;\}}\\ - \texttt{complex *32} & \texttt{struct \{long double r,i;\}}\\ - \texttt{character[*...]} & \texttt{char *}\\ - \end{tabular} - \caption{Mapping Fortran types to C types.} - \label{tab:mapf2c} - \end{center} -\end{table} -Users may redefine these mappings by creating a \texttt{.f2py\_f2cmap} -file in the working directory. This file should contain a Python -dictionary of dictionaries, e.g. \texttt{\{'real':\{'low':'float'\}\}}, -that informs \fpy to map Fortran type \texttt{real(low)} -to C type \texttt{float} (here \texttt{PARAMETER low = ...}). - - -\subsection{Calling Fortran (Module) Routines} -\label{sec:callrout} - -When mixing Fortran and C codes, one has to know how function names -are mapped to low-level symbols in their object files. Different -compilers may use different conventions for this purpose. For example, gcc -appends the underscore \texttt{\_} to a Fortran routine name. Other -compilers may use upper case names, prepend or append different -symbols to Fortran routine names or both. In any case, if the -low-level symbols corresponding to Fortran routines are valid for the -C language specification, compiler specific issues can be solved by -using CPP macro features. - -Unfortunately, there are Fortran compilers that use symbols in -constructing low-level routine names that are not valid for C. For -example, the (IRIX64) MIPSpro 7 Compilers use `\$' character in the -low-level names of module routines which makes it impossible (at -least directly) to call such routines from C when using the MIPSpro 7 -C Compiler. - -In order to overcome this difficulty, FPIG introduces a unique -solution: instead of using low-level symbols for calling Fortran -module routines from C, the references to such routines are determined -at run-time by using special wrappers. These wrappers are called once -during the initialization of an extension module. They are simple -Fortran subroutines that use a Fortran module and call another C -function with Fortran module routines as arguments in order to save -their references to C global variables that are later used for calling -the corresponding Fortran module routines. This arrangement is -set up as follows. Consider the following Fortran 90 module with the -subroutine \texttt{bar}: -\special{html:<BLOCKQUOTE>} -\begin{verbatim} -module fun - subroutine bar() - end -end -\end{verbatim} -\special{html:</BLOCKQUOTE>} -Figure \ref{fig:capi-sketch} illustrates a Python C/API extension -module for accessing the F90 module subroutine \texttt{bar} from Python. -When the Python module \texttt{foo} is loaded, \texttt{finitbar} is -called. \texttt{finitbar} calls \texttt{init\_bar} by passing the -reference of the Fortran 90 module subroutine \texttt{bar} to C where it is -saved to the variable \texttt{bar\_ptr}. Now, when one executes \texttt{foo.bar()} -from Python, \texttt{bar\_ptr} is used in \texttt{bar\_capi} to call -the F90 module subroutine \texttt{bar}. -\begin{figure}[htb] - \latexhide{\label{fig:capi-sketch}} - \special{html:<BLOCKQUOTE>} -\begin{verbatim} -#include "Python.h" -... -char *bar_ptr; -void init_bar(char *bar) { - bar_ptr = bar; -} -static PyObject * -bar_capi(PyObject *self,PyObject *args) { - ... - (*((void *)bar_ptr))(); - ... -} -static PyMethodDef -foo_module_methods[] = { - {"bar",bar_capi,METH_VARARGS}, - {NULL,NULL} -}; -extern void finitbar_; /* GCC convention */ -void initfoo() { - ... - finitbar_(init_bar); - Py_InitModule("foo",foo_module_methods); - ... -} -\end{verbatim} - \special{html:</BLOCKQUOTE>} - \caption{Sketch of Python C/API for accessing F90 module subroutine - \texttt{bar}. The Fortran function \texttt{finitbar} is defined in - Fig.~\ref{fig:wrapbar}.} - \tthhide{\label{fig:capi-sketch}} -\end{figure} -\begin{figure}[ht] - \latexhide{\label{fig:wrapbar}} -\special{html:<BLOCKQUOTE>} -\begin{verbatim} - subroutine finitbar(cinit) - use fun - extern cinit - call cinit(bar) - end -\end{verbatim} -\special{html:</BLOCKQUOTE>} - \caption{Wrapper for passing the reference of \texttt{bar} to C code.} - \tthhide{\label{fig:wrapbar}} -\end{figure} - -Surprisingly, mixing C code and Fortran modules in this way is as -portable and compiler independent as mixing C and ordinary Fortran~77 -code. - -Note that extension modules generated by \fpy actually use -\texttt{PyFortranObject} that implements above described scheme with -exchanged functionalities (see Section \ref{sec:PFO}). - - -\subsection{Wrapping Fortran Functions} -\label{sec:wrapfunc} - -The Fortran language has two types of routines: subroutines and -functions. When a Fortran function returns a composed type such as -\texttt{COMPLEX} or \texttt{CHARACTER}-array then calling this -function directly from C may not work for all compilers, as C -functions are not supposed to return such references. In order to -avoid this, FPIG constructs an additional Fortran wrapper subroutine -for each such Fortran function. These wrappers call just the -corresponding functions in the Fortran layer and return the result to -C through its first argument. - - -\subsection{Accessing Fortran Data} -\label{sec:accsdata} - -In Fortran one can use \texttt{COMMON} blocks and Fortran module -variables to save data that is accessible from other routines. Using -FPIG, one can also access these data containers from Python. To achieve -this, FPIG uses special wrapper functions (similar to the ones used -for wrapping Fortran module routines) to save the references to these -data containers so that they can later be used from C. - -FPIG can also handle \texttt{allocatable} arrays. For example, if a -Fortran array is not yet allocated, then by assigning it in Python, -the Fortran to Python interface will allocate and initialize the -array. For example, the F90 module allocatable array \texttt{bar} -defined in -\special{html:<BLOCKQUOTE>} -\begin{verbatim} -module fun - integer, allocatable :: bar(:) -end module -\end{verbatim} -\special{html:</BLOCKQUOTE>} -can be allocated from Python as follows -\special{html:<BLOCKQUOTE>} -\begin{verbatim} ->>> import foo ->>> foo.fun.bar = [1,2,3,4] -\end{verbatim} -\special{html:</BLOCKQUOTE>} - -\subsection{\texttt{PyFortranObject}} -\label{sec:PFO} - -In general, we would like to access from Python the following Fortran -objects: -\begin{itemize} -\item subroutines and functions, -\item F90 module subroutines and functions, -\item items in COMMON blocks, -\item F90 module data. -\end{itemize} -Assuming that the Fortran source is available, we can determine the signatures -of these objects (the full specification of routine arguments, the -layout of Fortran data, etc.). In fact, \fpy gets this information -while scanning the Fortran source. - -In order to access these Fortran objects from C, we need to determine -their references. Note that the direct access of F90 module objects is -extremely compiler dependent and in some cases even impossible. -Therefore, FPIG uses various wrapper functions for obtaining the -references to Fortran objects. These wrapper functions are ordinary -F77 subroutines that can easily access objects from F90 modules and -that pass the references to Fortran objects as C variables. - - -\fpy generated Python C/API extension modules use -\texttt{PyFortranObject} to store the references of Fortran objects. -In addition to the storing functionality, the \texttt{PyFortranObject} -also provides methods for accessing/calling Fortran objects from -Python in a user-friendly manner. For example, the item \texttt{a} in -\texttt{COMMON /bar/ a(2)} can be accessed from Python as -\texttt{foo.bar.a}. - -Detailed examples of \texttt{PyFortranObject} usage can be found in -\cite{PFO}. - -\subsection{Callback Functions} -\label{sec:callback} - -Fortran routines may have arguments specified as \texttt{external}. -These arguments are functions or subroutines names that the receiving Fortran routine -will call from its body. For such arguments FPIG -constructs a call-back mechanism (originally contributed by Travis -Oliphant) that allows Fortran routines to call Python functions. This -is actually realized using a C layer between Python and -Fortran. Currently, the call-back mechanism is compiler independent -unless a call-back function needs to return a composed type -(e.g. \texttt{COMPLEX}). - -The signatures of call-back functions are determined when \fpy scans -the Fortran source code. To illustrate this, consider the following -example: -\special{html:<BLOCKQUOTE>} -\begin{verbatim} - subroutine foo(bar, fun, boo) - integer i - real r - external bar,fun,boo - call bar(i, 1.2) - r = fun() - call sun(boo) - end -\end{verbatim} -\special{html:</BLOCKQUOTE>} -\fpy recognizes the signatures of the user routines \texttt{bar} and -\texttt{fun} using the information contained in the lines \texttt{call - bar(i, 1.2)} and \texttt{r = fun()}: -\special{html:<BLOCKQUOTE>} -\begin{verbatim} -subroutine bar(a,b) - integer a - real b -end -function fun() - real fun -end -\end{verbatim} -\special{html:</BLOCKQUOTE>} -But \fpy cannot determine the signature of the user routine -\texttt{boo} because the source contains no information at all about -the \texttt{boo} specification. Here user needs to provide the -signature of \texttt{boo} manually. - -\section{Future Work} -\label{sec:future} - -FPIG can be used to wrap almost any Fortran code. However, there are -still issues that need to be resolved. Some of them are listed below: -\begin{enumerate} -\item One of the FPIG's goals is to become as platform and compiler - independent as possible. Currently FPIG can be used on - any UN*X platform that has gcc installed in it. In the future, FPIG - should be also tested on Windows systems. -\item Another goal of FPIG is to become as simple to use as - possible. To achieve that, FPIG should start using the facilities of - \texttt{distutils}, the new Python standard to distribute and build - Python modules. Therefore, a contribution to \texttt{distutils} - that can handle Fortran extensions should be developed. -\item Currently users must be aware of - the fact that multi-dimensional arrays are stored differently in C - and Fortran (they must provide transposed multi-dimensional arrays - to wrapper functions). In the future a solution should be found such - that users do not need to worry about this rather - confusing and technical detail. -\item Finally, a repository of signature files for widely-used Fortran - libraries (e.g. BLAS, LAPACK, MINPACK, ODEPACK, EISPACK, LINPACK) should be - provided. -\end{enumerate} - - -\section{Application to a Large Aero-Structural Analysis Framework} -\label{sec:app} - - -\subsection{The Need for Python and FPIG} -\label{sec:appsub1} - -As a demonstration of the power and usefulness of FPIG, we will -present work that has been done at the Aerospace Computing Laboratory -at Stanford University. The focus of the research is on aircraft -design optimization using high-fidelity analysis tools such as -Computational Fluid Dynamics (CFD) and Computational Structural -Mechanics (CSM)~\cite{reno99}. - -The group's analysis programs are written mainly in Fortran and are the result -of many years of development. Until now, any researcher that needed -to use these tools would have to learn a less than user-friendly -interface and become relatively familiar with the inner workings of -the codes before starting the research itself. The need to -couple analyses of different disciplines revealed the additional -inconvenience of gluing and scripting the different codes with -Fortran. - -It was therefore decided that the existing tools should be wrapped -using an object-oriented language in order to improve their ease of -use and versatility. The use of several different languages such as -C++, Java and Perl was investigated but Python seemed to provide the -best solution. The fact that it combines scripting capability -with a fully-featured object-oriented programming language, and that -it has a clean syntax were factors that determined our choice. The -introduction of tools that greatly facilitate the task of wrapping -Fortran with Python provided the final piece needed to realize our -objective. - -\subsection{Wrapping the Fortran Programs} - -In theory, it would have been possible to wrap our Fortran programs -with C and then with Python by hand. However, this would have been a -labor intensive task that would detract from our research. The use of -tools that automate the task of wrapping has been extremely useful. - -The first such tool that we used was PyFort. This tool created the C -wrappers and Python modules automatically, based on signature files -(\texttt{.pyf}) provided by the user. Although it made the task of -wrapping considerably easier, PyFort was limited by the fact that any -Fortran data that was needed at the Python level had to be passed in -the argument list of the Fortran subroutine. Since the bulk of the -data in our programs is shared by using Fortran~77 common blocks and -Fortran~90 modules, this required adding many more arguments to the -subroutine headers. Furthermore, since Fortran does not allow common -block variables or module data to be specified in a subroutine -argument list, a dummy pointer for each desired variable had to be -created and initialized. - -The search for a better solution to this problem led us to \fpy. -Since \fpy provides a solution for accessing common block and module -variables, there was no need to change the Fortran source anymore, -making the wrapping process even easier. With \fpy we also -experienced an increased level of automation since it produces the -signature files automatically, as well as a Makefile for the joint -compilation of the original Fortran and C wrapper codes. This increased -automation did not detract from its flexibility since it was always -possible to edit the signature files to provide different functionality. - -Once Python interfaces were created for each Fortran application -by running \fpy, it was just a matter of using Python to achieve the -final objective of developing an object-oriented framework for our -multidisciplinary solvers. The Python modules that we designed are -discussed in the following section. - - -\subsection{Module Design} -\label{ssec:module} - -The first objective of this effort was to design the classes for each -type of analysis, each representing an independent Python module. In -our case, we are interested in performing aero-structural analysis and -optimization of aircraft wings. We therefore needed an analysis tool -for the flow (CFD), another for analyzing the structure (CSM), as well -as a geometry database. In addition, we needed to interface these two -tools in order to analyze the coupled system. The object design for -each of these modules should be general enough that the underlying -analysis code in Fortran can be changed without changing the Python -interface. Another requirement was that the modules be usable on -their own for single discipline analysis. - -\subsubsection{Geometry} - -The \emph{Geometry} class provides a database for the outer mold -geometry of the aircraft. This database needs to be accessed by both -the flow and structural solvers. It contains a parametric description -of the aircraft's surface as well as methods that extract and update -this information. - - -\subsubsection{Flow} - -The flow solver was wrapped in a class called \emph{Flow}. The class -was designed so that it can wrap any type of CFD solver. It contains -two main objects: the computational mesh and a solver object. A graph -showing the hierarchy of the objects in \emph{Flow} is shown in -Fig.~\ref{fig:flow}. -\tthhide{ -\begin{figure}[h] - \centering - \epsfig{file=./flow.eps, angle=0, width=.7\linewidth} - \caption{The \emph{Flow} container class.} - \label{fig:flow} -\end{figure} -} -\latexhide{ -\begin{figure}[h] - \label{fig:flow} -\special{html: -<CENTER> - <IMG SRC="flow.jpg" WIDTH="400"> -</CENTER> -} - \caption{The \emph{Flow} container class.} -\end{figure} -} -Methods in the flow class include those used for the initialization of -all the class components as well as methods that write the current -solution to a file. - - -\subsubsection{Structure} - -The \emph{Structure} class wraps a structural analysis code. The class -stores the information about the structure itself in an object called -\emph{Model} which also provides methods for changing and exporting -its information. A list of the objects contained in this class can be -seen in Fig.~\ref{fig:structure}. -\tthhide{ -\begin{figure}[h] - \centering - \epsfig{file=./structure.eps, angle=0, width=.7\linewidth} - \caption{The \emph{Structure} container class.} - \label{fig:structure} -\end{figure} -} -\latexhide{ -\begin{figure}[h] - \label{fig:structure} -\special{html: -<CENTER> - <IMG SRC="structure.jpg" WIDTH="400"> -</CENTER> -} - \caption{The \emph{Structure} container class.} -\end{figure} -} -Since the \emph{Structure} class contains a -dictionary of \emph{LoadCase} objects, it is able to store and solve -multiple load cases, a capability that the original Fortran code -does not have. - - -\subsubsection{Aerostructure} - -The \emph{Aerostructure} class is the main class in the -aero-structural analysis module and contains a \emph{Geometry}, a -\emph{Flow} and a \emph{Structure}. In addition, the class defines -all the functions that are necessary to translate aerodynamic -loads to structural loads and structural displacements to -geometry surface deformations. - -One of the main methods of this class is the one that solves the -aeroelastic system. This method is printed below: -\begin{verbatim} -def Iterate(self, load_case): - """Iterates the aero-structural solution.""" - self.flow.Iterate() - self._UpdateStructuralLoads() - self.structure.CalcDisplacements(load_case) - self.structure.CalcStresses(load_case) - self._UpdateFlowMesh() - return -\end{verbatim} -This is indeed a very readable script, thanks to Python, and any -high-level changes to the solution procedure can be easily -implemented. -The \emph{Aerostructure} class also contains methods that export all -the information on the current solution for visualization, an example -of which is shown in the next section. - - -\subsection{Results} - -In order to visualize results, and because we needed to view results -from multiple disciplines simultaneously, we selected OpenDX. Output -files in DX format are written at the Python level and the result can -be seen in Fig.~\ref{fig:aerostructure} for the case of a transonic -airliner configuration. -\tthhide{ -\begin{figure*}[t] - \centering - \epsfig{file=./aerostructure.eps, angle=-90, width=\linewidth} - \caption{Aero-structural model and results.} - \label{fig:aerostructure} -\end{figure*} -} -\latexhide{ -\begin{figure}[h] - \label{fig:aerostructure} -\special{html: -<CENTER> - <IMG SRC="aerostructure.jpg" WIDTH="600"> -</CENTER> -} - \caption{Aero-structural model and results.} -\end{figure} -} - - -The figure illustrates the multidisciplinary nature of the -problem. The grid pictured in the background is the mesh used by the -flow solver and is colored by the pressure values computed at the -cell centers. The wing in the foreground and its outer surface is -clipped to show the internal structural components which are colored -by their stress value. - -In conclusion, \fpy and Python have been extremely useful tools in our -pursuit for increasing the usability and flexibility of existing Fortran -tools. - - -\begin{thebibliography}{99} -\bibitem{netlib} -\newblock Netlib repository at UTK and ORNL. -\newblock \\\wwwsite{http://www.netlib.org/} -\bibitem{python} -Python language. -\newblock \\\wwwsite{http://www.python.org/} -\bibitem{swig} -SWIG --- Simplified Wrapper and Interface Generator. -\newblock \\\wwwsite{http://www.swig.org/} -\bibitem{pyfort} -PyFort --- The Python-Fortran connection tool. -\newblock \\\wwwsite{http://pyfortran.sourceforge.net/} -\bibitem{fpig} -FPIG --- Fortran to Python Interface Generator. -\newblock \\\wwwsite{http://cens.ioc.ee/projects/f2py2e/} -\bibitem{numpy} -Numerical Extension to Python. -\newblock \\\wwwsite{http://numpy.sourceforge.net/} -\bibitem{graham-etal} -R. L. Graham, D. E. Knuth, and O. Patashnik. -\newblock {\em {C}oncrete {M}athematics: a foundation for computer science.} -\newblock Addison-Wesley, 1988 -\bibitem{f2py-ug} -P. Peterson. -\newblock {\em {\tt f2py} - Fortran to Python Interface Generator. Second Edition.} -\newblock 2000 -\newblock -\\\wwwsite{http://cens.ioc.ee/projects/f2py2e/usersguide.html} -\bibitem{python-doc:ext} -Python Documentation: Extending and Embedding. -\newblock \\\wwwsite{http://www.python.org/doc/ext/} -\bibitem{PFO} -P. Peterson. {\em {\tt PyFortranObject} example usages.} -\newblock 2001 -\newblock \\\wwwsite{http://cens.ioc.ee/projects/f2py2e/pyfobj.html} -\bibitem{reno99} -Reuther, J., J. J. Alonso, J. R. R. A. Martins, and -S. C. Smith. -\newblock ``A Coupled Aero-Structural Optimization Method for - Complete Aircraft Configurations'', -\newblock {\em Proceedings of the 37th Aerospace Sciences Meeting}, -\newblock AIAA Paper 1999-0187. Reno, NV, January, 1999 -\end{thebibliography} - -%\end{multicols} - -%\begin{figure}[htbp] -% \begin{center} -% \epsfig{file=aerostructure2b.ps,width=0.75\textwidth} -% \end{center} -%\end{figure} - - - -\end{document} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: t -%%% End: |