From cdd23ab0073fb899db34d4d66f3e4b184a82c466 Mon Sep 17 00:00:00 2001 From: Charles Harris Date: Sat, 24 Oct 2009 15:51:30 +0000 Subject: Replace \r by \n. --- numpy/f2py/doc/python9.tex | 2090 ++++++++++++++++++++-------------------- numpy/f2py/doc/win32_notes.txt | 169 ++-- 2 files changed, 1128 insertions(+), 1131 deletions(-) (limited to 'numpy/f2py/doc') diff --git a/numpy/f2py/doc/python9.tex b/numpy/f2py/doc/python9.tex index cda3cd18b..fdcd32f46 100644 --- a/numpy/f2py/doc/python9.tex +++ b/numpy/f2py/doc/python9.tex @@ -1,1046 +1,1044 @@ -\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{}} - -\newcommand{\tthhide}[1]{#1} -\newcommand{\latexhide}[1]{} -%%tth:\newcommand{\tthhide}[1]{} -%%tth:\newcommand{\latexhide}[1]{#1} - -\newcommand{\shell}[1]{ -\latexhide{ - \special{html: -
-
-sh> #1
-
-
} -} -\tthhide{ - \\[1ex] - \hspace*{1em} - \texttt{sh> \begin{minipage}[t]{0.8\textwidth}#1\end{minipage}}\\[1ex] -} -} - -\newcommand{\email}[1]{\special{html:}\texttt{<#1>}\special{html:}} -\newcommand{\wwwsite}[1]{\special{html:}{#1}\special{html:}} -\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: -Gzipped PS, -PDF -} - -\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:
} - \verbatiminput{examples/exp1.f} - \special{html:
} - \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:
} - {\tthhide{\small} - \verbatiminput{examples/exp1mess.txt} - } - \special{html:
} - \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:
} - \verbatiminput{examples/exp1session.txt} - \special{html:
} - \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 .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:
} - \verbatiminput{examples/foo.pyf} - \special{html:
} - \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:
} - \verbatiminput{examples/foom.pyf} - \special{html:
} - \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{} or - \texttt{:}. 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()} - \item - \texttt{depend([])}: used - for arguments that depend on other arguments in \texttt{}. - \item - \texttt{check([])}: used for checking the - correctness of input arguments. - \item - \texttt{note()}: 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 an 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:
} -\begin{verbatim} -module fun - subroutine bar() - end -end -\end{verbatim} -\special{html:
} -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:
} -\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:
} - \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:
} -\begin{verbatim} - subroutine finitbar(cinit) - use fun - extern cinit - call cinit(bar) - end -\end{verbatim} -\special{html:
} - \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:
} -\begin{verbatim} -module fun - integer, allocatable :: bar(:) -end module -\end{verbatim} -\special{html:
} -can be allocated from Python as follows -\special{html:
} -\begin{verbatim} ->>> import foo ->>> foo.fun.bar = [1,2,3,4] -\end{verbatim} -\special{html:
} - -\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:
} -\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:
} -\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:
} -\begin{verbatim} -subroutine bar(a,b) - integer a - real b -end -function fun() - real fun -end -\end{verbatim} -\special{html:
} -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: -
- -
-} - \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: -
- -
-} - \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: -
- -
-} - \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: - - +\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{}} + +\newcommand{\tthhide}[1]{#1} +\newcommand{\latexhide}[1]{} +%%tth:\newcommand{\tthhide}[1]{} +%%tth:\newcommand{\latexhide}[1]{#1} + +\newcommand{\shell}[1]{ +\latexhide{ + \special{html: +
+
+sh> #1
+
+
} +} +\tthhide{ + \\[1ex] + \hspace*{1em} + \texttt{sh> \begin{minipage}[t]{0.8\textwidth}#1\end{minipage}}\\[1ex] +} +} + +\newcommand{\email}[1]{\special{html:}\texttt{<#1>}\special{html:}} +\newcommand{\wwwsite}[1]{\special{html:}{#1}\special{html:}} +\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: +Gzipped PS, +PDF +} + +\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:
} + \verbatiminput{examples/exp1.f} + \special{html:
} + \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:
} + {\tthhide{\small} + \verbatiminput{examples/exp1mess.txt} + } + \special{html:
} + \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:
} + \verbatiminput{examples/exp1session.txt} + \special{html:
} + \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 .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:
} + \verbatiminput{examples/foo.pyf} + \special{html:
} + \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:
} + \verbatiminput{examples/foom.pyf} + \special{html:
} + \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{} or + \texttt{:}. 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()} + \item + \texttt{depend([])}: used + for arguments that depend on other arguments in \texttt{}. + \item + \texttt{check([])}: used for checking the + correctness of input arguments. + \item + \texttt{note()}: 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 an 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:
} +\begin{verbatim} +module fun + subroutine bar() + end +end +\end{verbatim} +\special{html:
} +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:
} +\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:
} + \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:
} +\begin{verbatim} + subroutine finitbar(cinit) + use fun + extern cinit + call cinit(bar) + end +\end{verbatim} +\special{html:
} + \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:
} +\begin{verbatim} +module fun + integer, allocatable :: bar(:) +end module +\end{verbatim} +\special{html:
} +can be allocated from Python as follows +\special{html:
} +\begin{verbatim} +>>> import foo +>>> foo.fun.bar = [1,2,3,4] +\end{verbatim} +\special{html:
} + +\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:
} +\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:
} +\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:
} +\begin{verbatim} +subroutine bar(a,b) + integer a + real b +end +function fun() + real fun +end +\end{verbatim} +\special{html:
} +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: +
+ +
+} + \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: +
+ +
+} + \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: +
+ +
+} + \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: diff --git a/numpy/f2py/doc/win32_notes.txt b/numpy/f2py/doc/win32_notes.txt index 1b7b9029c..691cac26e 100644 --- a/numpy/f2py/doc/win32_notes.txt +++ b/numpy/f2py/doc/win32_notes.txt @@ -1,85 +1,84 @@ -The following notes are from Eric Jones. - -My Setup: - -For Python/Fortran development, I run Windows 2000 and use the mingw32 -(www.mingw.org) set of gcc/g77 compilers and tools (gcc 2.95.2) to build python -extensions. I'll also ocassionally use MSVC for extension development, but -rarely on projects that include Fortran code. This short HOWTO describes how -I use f2py in the Windows environment. Pretty much everything is done from -a CMD (DOS) prompt, so you'll need to be familiar with using shell commands. - -Installing f2py: - -Before installing f2py, you'll need to install python. I use python2.1 (maybe -python2.2 will be out by the time you read this). Any version of Python beyond -version 1.52 should be fine. See www.python.org for info on installing Python. - -You'll also need Numeric which is available at -http://sourceforge.net/projects/numpy/. The latest version is 20.3. - -Since Pearu has moved to a setup.py script, installation is pretty easy. You -can download f2py from http://cens.ioc.ee/projects/f2py2e/. The latest public -release is http://cens.ioc.ee/projects/f2py2e/rel-3.x/f2py-3.latest.tgz. Even -though this is a .tgz file instead of a .zip file, most standard compression -utilities such as WinZip (www.winzip.com) handle unpacking .tgz files -automatically. Here are the download steps: - - 1. Download the latest version of f2py and save it to disk. - - 2. Use WinZip or some other tool to open the "f2py.xxx.tgz" file. - a. When WinZip says archive contains one file, "f2py.xxx.tar" - and ask if it should open it, respond with "yes". - b. Extract (use the extract button at the top) all the files - in the archive into a file. I'll use c:\f2py2e - - 3. Open a cmd prompt by clicking start->run and typing "cmd.exe". - Now type the following commands. - - C:\WINDOWS\SYSTEM32> cd c:\f2py2e - C:\F2PY2E> python setup.py install - - This will install f2py in the c:\python21\f2py2e directory. It - also copies a few scripts into the c:\python21\Scripts directory. - Thats all there is to installing f2py. Now lets set up the environment - so that f2py is easy to use. - - 4. You need to set up a couple of environement variables. The path - "c:\python21\Scripts" needs to be added to your path variables. - To do this, go to the enviroment variables settings page. This is - where it is on windows 2000: - - Desktop->(right click)My Computer->Properties->Advanced-> - Environment Variables - - a. Add "c:\python21\Scripts" to the end of the Path variable. - b. If it isn't already there, add ".py" to the PATHEXT variable. - This tells the OS to execute f2py.py even when just "f2py" is - typed at a command prompt. - - 5. Well, there actually isn't anything to be done here. The Python - installation should have taken care of associating .py files with - Python for execution, so you shouldn't have to do anything to - registry settings. - -To test your installation, open a new cmd prompt, and type the following: - - C:\WINDOWS\SYSTEM32> f2py - Usage: - f2py [] [[[only:]||[skip:]] \ - ] \ - [: ...] - ... - -This prints out the usage information for f2py. If it doesn't, there is -something wrong with the installation. - -Testing: -The f2py test scripts are kinda Unix-centric, so they don't work under windows. - -XXX include test script XXX. - -Compiler and setup.py issues: - -XXX - +The following notes are from Eric Jones. + +My Setup: + +For Python/Fortran development, I run Windows 2000 and use the mingw32 +(www.mingw.org) set of gcc/g77 compilers and tools (gcc 2.95.2) to build python +extensions. I'll also ocassionally use MSVC for extension development, but +rarely on projects that include Fortran code. This short HOWTO describes how +I use f2py in the Windows environment. Pretty much everything is done from +a CMD (DOS) prompt, so you'll need to be familiar with using shell commands. + +Installing f2py: + +Before installing f2py, you'll need to install python. I use python2.1 (maybe +python2.2 will be out by the time you read this). Any version of Python beyond +version 1.52 should be fine. See www.python.org for info on installing Python. + +You'll also need Numeric which is available at +http://sourceforge.net/projects/numpy/. The latest version is 20.3. + +Since Pearu has moved to a setup.py script, installation is pretty easy. You +can download f2py from http://cens.ioc.ee/projects/f2py2e/. The latest public +release is http://cens.ioc.ee/projects/f2py2e/rel-3.x/f2py-3.latest.tgz. Even +though this is a .tgz file instead of a .zip file, most standard compression +utilities such as WinZip (www.winzip.com) handle unpacking .tgz files +automatically. Here are the download steps: + + 1. Download the latest version of f2py and save it to disk. + + 2. Use WinZip or some other tool to open the "f2py.xxx.tgz" file. + a. When WinZip says archive contains one file, "f2py.xxx.tar" + and ask if it should open it, respond with "yes". + b. Extract (use the extract button at the top) all the files + in the archive into a file. I'll use c:\f2py2e + + 3. Open a cmd prompt by clicking start->run and typing "cmd.exe". + Now type the following commands. + + C:\WINDOWS\SYSTEM32> cd c:\f2py2e + C:\F2PY2E> python setup.py install + + This will install f2py in the c:\python21\f2py2e directory. It + also copies a few scripts into the c:\python21\Scripts directory. + Thats all there is to installing f2py. Now lets set up the environment + so that f2py is easy to use. + + 4. You need to set up a couple of environement variables. The path + "c:\python21\Scripts" needs to be added to your path variables. + To do this, go to the enviroment variables settings page. This is + where it is on windows 2000: + + Desktop->(right click)My Computer->Properties->Advanced-> + Environment Variables + + a. Add "c:\python21\Scripts" to the end of the Path variable. + b. If it isn't already there, add ".py" to the PATHEXT variable. + This tells the OS to execute f2py.py even when just "f2py" is + typed at a command prompt. + + 5. Well, there actually isn't anything to be done here. The Python + installation should have taken care of associating .py files with + Python for execution, so you shouldn't have to do anything to + registry settings. + +To test your installation, open a new cmd prompt, and type the following: + + C:\WINDOWS\SYSTEM32> f2py + Usage: + f2py [] [[[only:]||[skip:]] \ + ] \ + [: ...] + ... + +This prints out the usage information for f2py. If it doesn't, there is +something wrong with the installation. + +Testing: +The f2py test scripts are kinda Unix-centric, so they don't work under windows. + +XXX include test script XXX. + +Compiler and setup.py issues: + +XXX -- cgit v1.2.1