diff options
Diffstat (limited to 'numpy/f2py/doc')
47 files changed, 6155 insertions, 0 deletions
diff --git a/numpy/f2py/doc/Makefile b/numpy/f2py/doc/Makefile new file mode 100644 index 000000000..2f241da0a --- /dev/null +++ b/numpy/f2py/doc/Makefile @@ -0,0 +1,76 @@ +# Makefile for compiling f2py2e documentation (dvi, ps, html) +# Pearu Peterson <pearu@ioc.ee> + +REL=4 +TOP = usersguide +LATEXSRC = bugs.tex commands.tex f2py2e.tex intro.tex notes.tex signaturefile.tex +MAINLATEX = f2py2e + +LATEX = latex +PDFLATEX = pdflatex + +COLLECTINPUT = ./collectinput.py +INSTALLDATA = install -m 644 -c + +TTH = tth +TTHFILTER = sed -e "s/{{}\\\verb@/\\\texttt{/g" | sed -e "s/@{}}/}/g" | $(TTH) -L$(MAINLATEX) -i +TTHFILTER2 = sed -e "s/{{}\\\verb@/\\\texttt{/g" | sed -e "s/@{}}/}/g" | $(TTH) -Lpython9 -i +TTHFILTER3 = sed -e "s/{{}\\\verb@/\\\texttt{/g" | sed -e "s/@{}}/}/g" | $(TTH) -Lfortranobject -i +TTHMISSING = "\ +***************************************************************\n\ +Warning: Could not find tth (a TeX to HTML translator) \n\ + or an error arised was by tth\n\ +You can download tth from http://hutchinson.belmont.ma.us/tth/ \n\ +or\n\ +use your favorite LaTeX to HTML translator on file tmp_main.tex\n\ +***************************************************************\ +" + +all: dvi ps html clean +$(MAINLATEX).dvi: $(LATEXSRC) + $(LATEX) $(MAINLATEX).tex + $(LATEX) $(MAINLATEX).tex + $(LATEX) $(MAINLATEX).tex + $(PDFLATEX) $(MAINLATEX).tex +$(TOP).dvi: $(MAINLATEX).dvi + cp -f $(MAINLATEX).dvi $(TOP).dvi + mv -f $(MAINLATEX).pdf $(TOP).pdf +$(TOP).ps: $(TOP).dvi + dvips $(TOP).dvi -o +$(TOP).html: $(LATEXSRC) + $(COLLECTINPUT) < $(MAINLATEX).tex > tmp_$(MAINLATEX).tex + @test `which $(TTH)` && cat tmp_$(MAINLATEX).tex | $(TTHFILTER) > $(TOP).html\ + || echo -e $(TTHMISSING) +dvi: $(TOP).dvi +ps: $(TOP).ps + gzip -f $(TOP).ps +html: $(TOP).html + +python9: + cp -f python9.tex f2python9-final/src/ + cd f2python9-final && mk_html.sh + cd f2python9-final && mk_ps.sh + cd f2python9-final && mk_pdf.sh +pyfobj: + $(LATEX) fortranobject.tex + $(LATEX) fortranobject.tex + $(LATEX) fortranobject.tex + @test `which $(TTH)` && cat fortranobject.tex | $(TTHFILTER3) > pyfobj.html\ + || echo -e $(TTHMISSING) + dvips fortranobject.dvi -o pyfobj.ps + gzip -f pyfobj.ps + pdflatex fortranobject.tex + mv fortranobject.pdf pyfobj.pdf + +WWWDIR=/net/cens/home/www/unsecure/projects/f2py2e/ +wwwpage: all + $(INSTALLDATA) index.html $(TOP).html $(TOP).ps.gz $(TOP).dvi $(TOP).pdf \ + Release-$(REL).x.txt ../NEWS.txt win32_notes.txt $(WWWDIR) + $(INSTALLDATA) pyfobj.{ps.gz,pdf,html} $(WWWDIR) + $(INSTALLDATA) f2python9-final/f2python9.{ps.gz,pdf,html} f2python9-final/{flow,structure,aerostructure}.jpg $(WWWDIR) +clean: + rm -f tmp_$(MAINLATEX).* $(MAINLATEX).{aux,dvi,log,toc} +distclean: + rm -f tmp_$(MAINLATEX).* $(MAINLATEX).{aux,dvi,log,toc} + rm -f $(TOP).{ps,dvi,html,pdf,ps.gz} + rm -f *~ diff --git a/numpy/f2py/doc/Release-1.x.txt b/numpy/f2py/doc/Release-1.x.txt new file mode 100644 index 000000000..46d6fbf09 --- /dev/null +++ b/numpy/f2py/doc/Release-1.x.txt @@ -0,0 +1,27 @@ + +I am pleased to announce the first public release of f2py 1.116: + +Writing Python C/API wrappers for Fortran routines can be a very +tedious task, especially if a Fortran routine takes more than 20 +arguments but only few of them are relevant for the problems that they +solve. + +The Fortran to Python Interface Generator, or FPIG for short, is a +command line tool (f2py) for generating Python C/API modules for +wrapping Fortran 77 routines, accessing common blocks from Python, and +calling Python functions from Fortran (call-backs). + +The tool can be downloaded from + + http://cens.ioc.ee/projects/f2py2e/ + +where you can find also information about f2py features and its User's +Guide. + +f2py is released under the LGPL license. + +With regards, + Pearu Peterson <pearu@ioc.ee> + +<P><A HREF="http://cens.ioc.ee/projects/f2py2e/">f2py 1.116</A> - The +Fortran to Python Interface Generator (25-Jan-00) diff --git a/numpy/f2py/doc/Release-2.x.txt b/numpy/f2py/doc/Release-2.x.txt new file mode 100644 index 000000000..807eb0ca8 --- /dev/null +++ b/numpy/f2py/doc/Release-2.x.txt @@ -0,0 +1,77 @@ + +FPIG - Fortran to Python Interface Generator + +I am pleased to announce the second public release of f2py +(version 2.264): + + http://cens.ioc.ee/projects/f2py2e/ + +f2py is a command line tool for binding Python and Fortran codes. It +scans Fortran 77/90/95 codes and generates a Python C/API module that +makes it possible to call Fortran routines from Python. No Fortran or +C expertise is required for using this tool. + +Features include: + + *** All basic Fortran types are supported: + integer[ | *1 | *2 | *4 | *8 ], logical[ | *1 | *2 | *4 | *8 ], + character[ | *(*) | *1 | *2 | *3 | ... ] + real[ | *4 | *8 | *16 ], double precision, + complex[ | *8 | *16 | *32 ] + + *** Multi-dimensional arrays of (almost) all basic types. + Dimension specifications: + <dim> | <start>:<end> | * | : + + *** Supported attributes: + intent([ in | inout | out | hide | in,out | inout,out ]) + dimension(<dimspec>) + depend([<names>]) + check([<C-booleanexpr>]) + note(<LaTeX text>) + optional, required, external + + *** Calling Fortran 77/90/95 subroutines and functions. Also + Fortran 90/95 module routines. Internal initialization of + optional arguments. + + *** Accessing COMMON blocks from Python. Accessing Fortran 90/95 + module data coming soon. + + *** Call-back functions: calling Python functions from Fortran with + very flexible hooks. + + *** In Python, arguments of the interfaced functions may be of + different type - necessary type conversations are done + internally in C level. + + *** Automatically generates documentation (__doc__,LaTeX) for + interface functions. + + *** Automatically generates signature files --- user has full + control over the interface constructions. Automatically + detects the signatures of call-back functions, solves argument + dependencies, etc. + + *** Automatically generates Makefile for compiling Fortran and C + codes and linking them to a shared module. Many compilers are + supported: gcc, Compaq Fortran, VAST/f90 Fortran, Absoft + F77/F90, MIPSpro 7 Compilers, etc. Platforms: Intel/Alpha + Linux, HP-UX, IRIX64. + + *** Complete User's Guide in various formats (html,ps,pdf,dvi). + + *** f2py users list is available for support, feedback, etc. + +More information about f2py, see + + http://cens.ioc.ee/projects/f2py2e/ + +f2py is released under the LGPL license. + +Sincerely, + Pearu Peterson <pearu@ioc.ee> + September 12, 2000 + +<P><A HREF="http://cens.ioc.ee/projects/f2py2e/">f2py 2.264</A> - The +Fortran to Python Interface Generator (12-Sep-00) diff --git a/numpy/f2py/doc/Release-3.x.txt b/numpy/f2py/doc/Release-3.x.txt new file mode 100644 index 000000000..940771015 --- /dev/null +++ b/numpy/f2py/doc/Release-3.x.txt @@ -0,0 +1,87 @@ + +F2PY - Fortran to Python Interface Generator + +I am pleased to announce the third public release of f2py +(version 2.3.321): + + http://cens.ioc.ee/projects/f2py2e/ + +f2py is a command line tool for binding Python and Fortran codes. It +scans Fortran 77/90/95 codes and generates a Python C/API module that +makes it possible to call Fortran subroutines from Python. No Fortran or +C expertise is required for using this tool. + +Features include: + + *** All basic Fortran types are supported: + integer[ | *1 | *2 | *4 | *8 ], logical[ | *1 | *2 | *4 | *8 ], + character[ | *(*) | *1 | *2 | *3 | ... ] + real[ | *4 | *8 | *16 ], double precision, + complex[ | *8 | *16 | *32 ] + + *** Multi-dimensional arrays of (almost) all basic types. + Dimension specifications: + <dim> | <start>:<end> | * | : + + *** Supported attributes and statements: + intent([ in | inout | out | hide | in,out | inout,out ]) + dimension(<dimspec>) + depend([<names>]) + check([<C-booleanexpr>]) + note(<LaTeX text>) + optional, required, external +NEW: intent(c), threadsafe, fortranname + + *** Calling Fortran 77/90/95 subroutines and functions. Also + Fortran 90/95 module subroutines are supported. Internal + initialization of optional arguments. + + *** Accessing COMMON blocks from Python. +NEW: Accessing Fortran 90/95 module data. + + *** Call-back functions: calling Python functions from Fortran with + very flexible hooks. + + *** In Python, arguments of the interfaced functions may be of + different type - necessary type conversations are done + internally in C level. + + *** Automatically generates documentation (__doc__,LaTeX) for + interfaced functions. + + *** Automatically generates signature files --- user has full + control over the interface constructions. Automatically + detects the signatures of call-back functions, solves argument + dependencies, etc. + +NEW: * Automatically generates setup_<modulename>.py for building + extension modules using tools from distutils and + fortran_support module (SciPy). + + *** Automatically generates Makefile for compiling Fortran and C + codes and linking them to a shared module. Many compilers are + supported: gcc, Compaq Fortran, VAST/f90 Fortran, Absoft + F77/F90, MIPSpro 7 Compilers, etc. Platforms: Intel/Alpha + Linux, HP-UX, IRIX64. + + *** Complete User's Guide in various formats (html,ps,pdf,dvi). + + *** f2py users list is available for support, feedback, etc. + +NEW: * Installation with distutils. + + *** And finally, many bugs are fixed. + +More information about f2py, see + + http://cens.ioc.ee/projects/f2py2e/ + +LICENSE: + f2py is released under the LGPL. + +Sincerely, + Pearu Peterson <pearu@cens.ioc.ee> + December 4, 2001 + +<P><A HREF="http://cens.ioc.ee/projects/f2py2e/">f2py 2.3.321</A> - The +Fortran to Python Interface Generator (04-Dec-01) diff --git a/numpy/f2py/doc/Release-4.x.txt b/numpy/f2py/doc/Release-4.x.txt new file mode 100644 index 000000000..ed071a0cb --- /dev/null +++ b/numpy/f2py/doc/Release-4.x.txt @@ -0,0 +1,91 @@ + +F2PY - Fortran to Python Interface Generator + +I am pleased to announce the fourth public release of f2py +(version 2.4.366): + + http://cens.ioc.ee/projects/f2py2e/ + +f2py is a command line tool for binding Python and Fortran codes. It +scans Fortran 77/90/95 codes and generates a Python C/API module that +makes it possible to call Fortran subroutines from Python. No Fortran or +C expertise is required for using this tool. + +New features: + *** Win32 support. + *** Better Python C/API generated code (-Wall is much less verbose). + +Features include: + + *** All basic Fortran types are supported: + integer[ | *1 | *2 | *4 | *8 ], logical[ | *1 | *2 | *4 | *8 ], + character[ | *(*) | *1 | *2 | *3 | ... ] + real[ | *4 | *8 | *16 ], double precision, + complex[ | *8 | *16 | *32 ] + + *** Multi-dimensional arrays of (almost) all basic types. + Dimension specifications: + <dim> | <start>:<end> | * | : + + *** Supported attributes and statements: + intent([ in | inout | out | hide | in,out | inout,out ]) + dimension(<dimspec>) + depend([<names>]) + check([<C-booleanexpr>]) + note(<LaTeX text>) + optional, required, external + intent(c), threadsafe, fortranname + + *** Calling Fortran 77/90/95 subroutines and functions. Also + Fortran 90/95 module subroutines are supported. Internal + initialization of optional arguments. + + *** Accessing COMMON blocks from Python. + Accessing Fortran 90/95 module data. + + *** Call-back functions: calling Python functions from Fortran with + very flexible hooks. + + *** In Python, arguments of the interfaced functions may be of + different type - necessary type conversations are done + internally in C level. + + *** Automatically generates documentation (__doc__,LaTeX) for + interfaced functions. + + *** Automatically generates signature files --- user has full + control over the interface constructions. Automatically + detects the signatures of call-back functions, solves argument + dependencies, etc. + + *** Automatically generates setup_<modulename>.py for building + extension modules using tools from distutils and + fortran_support module (SciPy). + + *** Automatically generates Makefile for compiling Fortran and C + codes and linking them to a shared module. Many compilers are + supported: gcc, Compaq Fortran, VAST/f90 Fortran, Absoft + F77/F90, MIPSpro 7 Compilers, etc. Platforms: Intel/Alpha + Linux, HP-UX, IRIX64. + + *** Complete User's Guide in various formats (html,ps,pdf,dvi). + + *** f2py users list is available for support, feedback, etc. + + *** Installation with distutils. + + *** And finally, many bugs are fixed. + +More information about f2py, see + + http://cens.ioc.ee/projects/f2py2e/ + +LICENSE: + f2py is released under the LGPL. + +Sincerely, + Pearu Peterson <pearu@cens.ioc.ee> + December 17, 2001 + +<P><A HREF="http://cens.ioc.ee/projects/f2py2e/">f2py 2.4.366</A> - The +Fortran to Python Interface Generator (17-Dec-01) diff --git a/numpy/f2py/doc/apps.tex b/numpy/f2py/doc/apps.tex new file mode 100644 index 000000000..513c048bd --- /dev/null +++ b/numpy/f2py/doc/apps.tex @@ -0,0 +1,71 @@ + +\section{Applications} +\label{sec:apps} + + +\subsection{Example: wrapping C library \texttt{fftw}} +\label{sec:wrapfftw} + +Here follows a simple example how to use \fpy to generate a wrapper +for C functions. Let us create a FFT code using the functions in FFTW +library. I'll assume that the library \texttt{fftw} is configured with +\texttt{-{}-enable-shared} option. + +Here is the wrapper for the typical usage of FFTW: +\begin{verbatim} +/* File: wrap_dfftw.c */ +#include <dfftw.h> + +extern void dfftw_one(fftw_complex *in,fftw_complex *out,int *n) { + fftw_plan p; + p = fftw_create_plan(*n,FFTW_FORWARD,FFTW_ESTIMATE); + fftw_one(p,in,out); + fftw_destroy_plan(p); +} +\end{verbatim} +and here follows the corresponding siganture file (created manually): +\begin{verbatim} +!%f90 +! File: fftw.f90 +module fftw + interface + subroutine dfftw_one(in,out,n) + integer n + complex*16 in(n),out(n) + intent(out) out + intent(hide) n + end subroutine dfftw_one + end interface +end module fftw +\end{verbatim} + +Now let us generate the Python C/API module with \fpy: +\begin{verbatim} +f2py fftw.f90 +\end{verbatim} +and compile it +\begin{verbatim} +gcc -shared -I/numeric/include -I`f2py -I` -L/numeric/lib -ldfftw \ + -o fftwmodule.so -DNO_APPEND_FORTRAN fftwmodule.c wrap_dfftw.c +\end{verbatim} + +In Python: +\begin{verbatim} +>>> from Numeric import * +>>> from fftw import * +>>> print dfftw_one.__doc__ +Function signature: + out = dfftw_one(in) +Required arguments: + in : input rank-1 array('D') with bounds (n) +Return objects: + out : rank-1 array('D') with bounds (n) +>>> print dfftw_one([1,2,3,4]) +[ 10.+0.j -2.+2.j -2.+0.j -2.-2.j] +>>> +\end{verbatim} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "f2py2e" +%%% End: diff --git a/numpy/f2py/doc/bugs.tex b/numpy/f2py/doc/bugs.tex new file mode 100644 index 000000000..699ecf530 --- /dev/null +++ b/numpy/f2py/doc/bugs.tex @@ -0,0 +1,109 @@ + +\section{Bugs, Plans, and Feedback} +\label{sec:bugs} + +Currently no bugs have found that I was not able to fix. I will be +happy to receive bug reports from you (so that I could fix them and +keep the first sentence of this paragraph as true as possible ;-). +Note that \fpy is developed to work properly with gcc/g77 +compilers. +\begin{description} +\item[NOTE:] Wrapping callback functions returning \texttt{COMPLEX} + may fail on some systems. Workaround: avoid it by using callback + subroutines. +\end{description} + +Here follows a list of things that I plan to implement in (near) future: +\begin{enumerate} +\item recognize file types by their extension (signatures: + \texttt{*.pyf}, Fortran 77, Fortran 90 fixed: \texttt{*.f, *.for, *.F, *.FOR}, + Fortran 90 free: \texttt{*.F90, *.f90, *.m, *.f95, *.F95}); [DONE] +\item installation using \texttt{distutils} (when it will be stable); +\item put out to the web examples of \fpy usages in real situations: + wrapping \texttt{vode}, for example; +\item implement support for \texttt{PARAMETER} statement; [DONE] +\item rewrite test-site; +\item ... +\end{enumerate} +and here are things that I plan to do in future: +\begin{enumerate} +\item implement \texttt{intent(cache)} attribute for an optional work + arrays with a feature of allocating additional memory if needed; +\item use \fpy for wrapping Fortran 90/95 codes. \fpy should scan + Fortran 90/95 codes with no problems, what needs to be done is find + out how to call a Fortran 90/95 function (from a module) from + C. Anybody there willing to test \fpy with Fortran 90/95 modules? [DONE] +\item implement support for Fortran 90/95 module data; [DONE] +\item implement support for \texttt{BLOCK DATA} blocks (if needed); +\item test/document \fpy for \texttt{CHARACTER} arrays; +\item decide whether internal transposition of multi-dimensional + arrays is reasonable (need efficient code then), even if this is + controlled by the user trough some additional keyword; need + consistent and safe policy here; +\item use \fpy for generating wrapper functions also for C programs (a + kind of SWIG, only between Python and C). For that \fpy needs a + command line switch to inform itself that C scalars are passed in by + their value, not by their reference, for instance; +\item introduce a counter that counts the number of inefficient usages + of wrapper functions (copying caused by type-casting, non-contiguous + arrays); +\item if needed, make \texttt{DATA} statement to work properly for + arrays; +\item rewrite \texttt{COMMON} wrapper; [DONE] +\item ... +\end{enumerate} +I'll appreciate any feedback that will improve \fpy (bug reports, +suggestions, etc). If you find a correct Fortran code that fails with +\fpy, try to send me a minimal version of it so that I could track +down the cause of the failure. Note also that there is no sense to +send me files that are auto-generated with \fpy (I can generate them +myself); the version of \fpy that you are using (run \texttt{\fpy\ + -v}), and the relevant fortran codes or modified signature files +should be enough information to fix the bugs. Also add some +information on compilers and linkers that you use to the bug report. + + +\section{History of \fpy} +\label{sec:history} + +\begin{enumerate} +\item I was driven to start developing a tool such as \fpy after I had + wrote several Python C/API modules for interfacing various Fortran + routines from the Netlib. This work was tedious (some of functions + had more than 20 arguments, only few of them made sense for the + problems that they solved). I realized that most of the writing + could be done automatically. +\item On 9th of July, 1999, the first lines of the tool was written. A + prototype of the tool was ready to use in only three weeks. During + this time Travis Oliphant joined to the project and shared his + valuable knowledge and experience; the call-back mechanism is his + major contribution. Then I gave the tool to public under the name + FPIG --- \emph{Fortran to Python Interface Generator}. The tool contained + only one file \texttt{f2py.py}. +\item By autumn, it was clear that a better implementation was needed + as the debugging process became very tedious. So, I reserved some + time and rewrote the tool from scratch. The most important result of + this rewriting was the code that reads real Fortran codes and + determines the signatures of the Fortran routines. The main + attention was payed in particular to this part so that the tool + could read arbitrary Fortran~77/90/95 codes. As a result, the other + side of the tools task, that is, generating Python C/API functions, + was not so great. In public, this version of the tool was called + \texttt{f2py2e} --- \emph{Fortran to Python C/API generator, the + Second Edition}. +\item So, a month before The New Year 2000, I started the third + iteration of the \fpy development. Now the main attention was to + have a good C/API module constructing code. By 21st of January, + 2000, the tool of generating wrapper functions for Fortran routines + was ready. It had many new features and was more robust than ever. +\item In 25th of January, 2000, the first public release of \fpy was + announced (version 1.116). +\item In 12th of September, 2000, the second public release of \fpy was + announced (version 2.264). It now has among other changes a support + for Fortran 90/95 module routines. +\end{enumerate} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "f2py2e" +%%% End: diff --git a/numpy/f2py/doc/collectinput.py b/numpy/f2py/doc/collectinput.py new file mode 100755 index 000000000..2e3a09d9d --- /dev/null +++ b/numpy/f2py/doc/collectinput.py @@ -0,0 +1,74 @@ +#!/usr/bin/env python +""" +collectinput - Collects all files that are included to a main Latex document + with \input or \include commands. These commands must be + in separate lines. + +Copyright 1999 Pearu Peterson all rights reserved, +Pearu Peterson <pearu@ioc.ee> +Permission to use, modify, and distribute this software is given under the +terms of the NumPy License + +NO WARRANTY IS EXPRESSED OR IMPLIED. USE AT YOUR OWN RISK. + +Pearu Peterson + +Usage: + collectinput <infile> <outfile> + collectinput <infile> # <outfile>=inputless_<infile> + collectinput # in and out are stdin and stdout +""" + +__version__ = "0.0" + +stdoutflag=0 +import sys,os,string,fileinput,re,commands + +try: fn=sys.argv[2] +except: + try: fn='inputless_'+sys.argv[1] + except: stdoutflag=1 +try: fi=sys.argv[1] +except: fi=() +if not stdoutflag: + sys.stdout=open(fn,'w') + +nonverb=r'[\w\s\\&=\^\*\.\{\(\)\[\?\+\$/]*(?!\\verb.)' +input=re.compile(nonverb+r'\\(input|include)\*?\s*\{?.*}?') +comment=re.compile(r'[^%]*%') + +for l in fileinput.input(fi): + l=l[:-1] + l1='' + if comment.match(l): + m=comment.match(l) + l1=l[m.end()-1:] + l=l[:m.end()-1] + m=input.match(l) + if m: + l=string.strip(l) + if l[-1]=='}': l=l[:-1] + i=m.end()-2 + sys.stderr.write('>>>>>>') + while i>-1 and (l[i] not in [' ','{']): i=i-1 + if i>-1: + fn=l[i+1:] + try: f=open(fn,'r'); flag=1; f.close() + except: + try: f=open(fn+'.tex','r'); flag=1;fn=fn+'.tex'; f.close() + except: flag=0 + if flag==0: + sys.stderr.write('Could not open a file: '+fn+'\n') + print l+l1 + continue + elif flag==1: + sys.stderr.write(fn+'\n') + print '%%%%% Begin of '+fn + print commands.getoutput(sys.argv[0]+' < '+fn) + print '%%%%% End of '+fn + else: + sys.stderr.write('Could not extract a file name from: '+l) + print l+l1 + else: + print l+l1 +sys.stdout.close() diff --git a/numpy/f2py/doc/commands.tex b/numpy/f2py/doc/commands.tex new file mode 100644 index 000000000..5101a9ff5 --- /dev/null +++ b/numpy/f2py/doc/commands.tex @@ -0,0 +1,20 @@ +\usepackage{xspace} +\usepackage{verbatim} + +%%tth:\newcommand{\xspace}{ } + +\newcommand{\fpy}{\texttt{f2py}\xspace} + +\newcommand{\bs}{\symbol{`\\}} +% need bs here: +%%tth:\newcommand{\bs}{\texttt{<backslash>}} + +\newcommand{\shell}[1]{\hspace*{1em}\texttt{sh> \begin{minipage}[t]{0.8\textwidth}#1\end{minipage}}} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "f2py2e" +%%% End: + + diff --git a/numpy/f2py/doc/ex1/arr.f b/numpy/f2py/doc/ex1/arr.f new file mode 100644 index 000000000..c4e49988f --- /dev/null +++ b/numpy/f2py/doc/ex1/arr.f @@ -0,0 +1,4 @@ + subroutine arr(l,m,n,a) + integer l,m,n + real*8 a(l,m,n) + end diff --git a/numpy/f2py/doc/ex1/bar.f b/numpy/f2py/doc/ex1/bar.f new file mode 100644 index 000000000..c723b5af1 --- /dev/null +++ b/numpy/f2py/doc/ex1/bar.f @@ -0,0 +1,4 @@ + function bar(a,b) + integer a,b,bar + bar = a + b + end diff --git a/numpy/f2py/doc/ex1/foo.f b/numpy/f2py/doc/ex1/foo.f new file mode 100644 index 000000000..cdcac4103 --- /dev/null +++ b/numpy/f2py/doc/ex1/foo.f @@ -0,0 +1,5 @@ + subroutine foo(a) + integer a +cf2py intent(in,out) :: a + a = a + 5 + end diff --git a/numpy/f2py/doc/ex1/foobar-smart.f90 b/numpy/f2py/doc/ex1/foobar-smart.f90 new file mode 100644 index 000000000..61385a685 --- /dev/null +++ b/numpy/f2py/doc/ex1/foobar-smart.f90 @@ -0,0 +1,24 @@ +!%f90 +module foobar ! in + note(This module contains two examples that are used in & + \texttt{f2py} documentation.) foobar + interface ! in :foobar + subroutine foo(a) ! in :foobar:foo.f + note(Example of a wrapper function of a Fortran subroutine.) foo + integer intent(inout),& + note(5 is added to the variable {{}\verb@a@{}} ``in place''.) :: a + end subroutine foo + function bar(a,b) result (ab) ! in :foobar:bar.f + integer :: a + integer :: b + integer :: ab + note(The first value.) a + note(The second value.) b + note(Add two values.) bar + note(The result.) ab + end function bar + end interface +end module foobar + +! This file was auto-generated with f2py (version:0.95). +! See http://cens.ioc.ee/projects/f2py2e/ diff --git a/numpy/f2py/doc/ex1/foobar.f90 b/numpy/f2py/doc/ex1/foobar.f90 new file mode 100644 index 000000000..53ac5b506 --- /dev/null +++ b/numpy/f2py/doc/ex1/foobar.f90 @@ -0,0 +1,16 @@ +!%f90 +module foobar ! in + interface ! in :foobar + subroutine foo(a) ! in :foobar:foo.f + integer intent(inout) :: a + end subroutine foo + function bar(a,b) ! in :foobar:bar.f + integer :: a + integer :: b + integer :: bar + end function bar + end interface +end module foobar + +! This file was auto-generated with f2py (version:0.95). +! See http://cens.ioc.ee/projects/f2py2e/ diff --git a/numpy/f2py/doc/ex1/foobarmodule.tex b/numpy/f2py/doc/ex1/foobarmodule.tex new file mode 100644 index 000000000..32411ec03 --- /dev/null +++ b/numpy/f2py/doc/ex1/foobarmodule.tex @@ -0,0 +1,36 @@ +% This file is auto-generated with f2py (version:2.266) +\section{Module \texttt{foobar}} + +This module contains two examples that are used in \texttt{f2py} documentation. + +\subsection{Wrapper function \texttt{foo}} + + +\noindent{{}\verb@foo@{}}\texttt{(a)} +--- Example of a wrapper function of a Fortran subroutine. + +\noindent Required arguments: +\begin{description} +\item[]{{}\verb@a : in/output rank-0 array(int,'i')@{}} +--- 5 is added to the variable {{}\verb@a@{}} ``in place''. +\end{description} + +\subsection{Wrapper function \texttt{bar}} + + +\noindent{{}\verb@bar = bar@{}}\texttt{(a, b)} +--- Add two values. + +\noindent Required arguments: +\begin{description} +\item[]{{}\verb@a : input int@{}} +--- The first value. +\item[]{{}\verb@b : input int@{}} +--- The second value. +\end{description} +\noindent Return objects: +\begin{description} +\item[]{{}\verb@bar : int@{}} +--- See elsewhere. +\end{description} + diff --git a/numpy/f2py/doc/ex1/runme b/numpy/f2py/doc/ex1/runme new file mode 100755 index 000000000..2aac6158e --- /dev/null +++ b/numpy/f2py/doc/ex1/runme @@ -0,0 +1,18 @@ +#!/bin/sh + +f2py2e='python ../../f2py2e.py' +PYINC=`$f2py2e -pyinc` +$f2py2e foobar-smart.pyf --short-latex --overwrite-makefile -makefile foo.f bar.f +gmake -f Makefile-foobar +#gcc -O3 -I$PYINC -I$PYINC/Numeric -shared -o foobarmodule.so foobarmodule.c foo.f bar.f +python -c ' +import foobar +print foobar.__doc__ +print foobar.bar(2,3) +from Numeric import * +a=array(3) +print a,foobar.foo(a),a +print foobar.foo.__doc__ +print foobar.bar.__doc__ +print "ok" +' diff --git a/numpy/f2py/doc/f2py2e.tex b/numpy/f2py/doc/f2py2e.tex new file mode 100644 index 000000000..6e3e9d68c --- /dev/null +++ b/numpy/f2py/doc/f2py2e.tex @@ -0,0 +1,50 @@ +\documentclass{article} +\usepackage{a4wide} + +\input commands + +\title{\fpy\\Fortran to Python Interface Generator\\{\large Second Edition}} +\author{Pearu Peterson \texttt{<pearu@ioc.ee>}} +\date{$Revision: 1.16 $\\\today} +\begin{document} +\special{html: <font size=-1>If equations does not show Greek letters or large + brackets correctly, then your browser configuration needs some + adjustment. Read the notes for <A + href=http://hutchinson.belmont.ma.us/tth/Xfonts.html>Enabling Symbol + Fonts in Netscape under X </A>. In addition, the browser must be set + to use document fonts. </font> +} + +\maketitle +\begin{abstract} + \fpy is a Python program that generates Python C/API modules for + wrapping Fortran~77/90/95 codes to Python. The user can influence the + process by modifying the signature files that \fpy generates when + scanning the Fortran codes. This document describes the syntax of + the signature files and the ways how the user can dictate the tool + to produce wrapper functions with desired Python signatures. Also + how to call the wrapper functions from Python is discussed. + + See \texttt{http://cens.ioc.ee/projects/f2py2e/} for updates of this + document and the tool. +\end{abstract} + +\tableofcontents + +\input intro +\input signaturefile +\input notes +\input options +\input bugs + +\appendix +\input ex1/foobarmodule +\input apps +\end{document} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: + + diff --git a/numpy/f2py/doc/f2python9-final/README.txt b/numpy/f2py/doc/f2python9-final/README.txt new file mode 100644 index 000000000..b907216b6 --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/README.txt @@ -0,0 +1,38 @@ + +This directory contains the source of the paper + + "Fortran to Python Interface Generator with an Application + to Aerospace Engineering" + +by + Pearu Peterson <pearu@cens.ioc.ee> (the corresponding author) + Joaquim R. R. A. Martins <joaquim.martins@stanford.edu> + Juan J. Alonso <jjalonso@stanford.edu> + +for The 9th International Python Conference, March 5-8, 2001, Long Beach, California. + +The paper is provided here is in the HTML format: + + f2python9.html (size=48151 bytes) + +Note that this file includes the following JPG images + + flow.jpg (size=13266) + structure.jpg (size=17860) + aerostructure.jpg (size=72247) + +PS: +The HTML file f2python9.html is generated using TTH (http://hutchinson.belmont.ma.us/tth/) +from the LaTeX source file `python9.tex'. The source can be found in the + src/ +directory. This directory contains also the following EPS files + flow.eps + structure.eps + aerostructure.eps +and the text files + examples/{exp1.f,exp1mess.txt,exp1session.txt,foo.pyf,foom.pyf} +that are used by the LaTeX source python9.tex. + +Regards, + Pearu +January 15, 2001 diff --git a/numpy/f2py/doc/f2python9-final/aerostructure.jpg b/numpy/f2py/doc/f2python9-final/aerostructure.jpg Binary files differnew file mode 100644 index 000000000..896ad6e12 --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/aerostructure.jpg diff --git a/numpy/f2py/doc/f2python9-final/flow.jpg b/numpy/f2py/doc/f2python9-final/flow.jpg Binary files differnew file mode 100644 index 000000000..cfe0f85f3 --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/flow.jpg diff --git a/numpy/f2py/doc/f2python9-final/mk_html.sh b/numpy/f2py/doc/f2python9-final/mk_html.sh new file mode 100755 index 000000000..944110e93 --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/mk_html.sh @@ -0,0 +1,13 @@ +#!/bin/sh +cd src + +test -f aerostructure.eps || convert ../aerostructure.jpg aerostructure.eps +test -f flow.eps || convert ../flow.jpg flow.eps +test -f structure.eps || convert ../structure.jpg structure.eps + +latex python9.tex +latex python9.tex +latex python9.tex + +test `which tth` && cat python9.tex | sed -e "s/{{}\\\verb@/\\\texttt{/g" | sed -e "s/@{}}/}/g" | tth -Lpython9 -i > ../f2python9.html +cd .. diff --git a/numpy/f2py/doc/f2python9-final/mk_pdf.sh b/numpy/f2py/doc/f2python9-final/mk_pdf.sh new file mode 100755 index 000000000..b773028b7 --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/mk_pdf.sh @@ -0,0 +1,13 @@ +#!/bin/sh +cd src + +test -f aerostructure.pdf || convert ../aerostructure.jpg aerostructure.pdf +test -f flow.pdf || convert ../flow.jpg flow.pdf +test -f structure.pdf || convert ../structure.jpg structure.pdf + +cat python9.tex | sed -e "s/eps,/pdf,/g" > python9pdf.tex +pdflatex python9pdf.tex +pdflatex python9pdf.tex +pdflatex python9pdf.tex + +mv python9pdf.pdf ../f2python9.pdf
\ No newline at end of file diff --git a/numpy/f2py/doc/f2python9-final/mk_ps.sh b/numpy/f2py/doc/f2python9-final/mk_ps.sh new file mode 100755 index 000000000..4b0863fcd --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/mk_ps.sh @@ -0,0 +1,14 @@ +#!/bin/sh +cd src + +test -f aerostructure.eps || convert ../aerostructure.jpg aerostructure.eps +test -f flow.eps || convert ../flow.jpg flow.eps +test -f structure.eps || convert ../structure.jpg structure.eps + +latex python9.tex +latex python9.tex +latex python9.tex + +dvips python9.dvi -o ../f2python9.ps +cd .. +gzip -f f2python9.ps diff --git a/numpy/f2py/doc/f2python9-final/src/examples/exp1.f b/numpy/f2py/doc/f2python9-final/src/examples/exp1.f new file mode 100644 index 000000000..36bee50b0 --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/src/examples/exp1.f @@ -0,0 +1,26 @@ + subroutine exp1(l,u,n) +C Input: n is number of iterations +C Output: l,u are such that +C l(1)/l(2) < exp(1) < u(1)/u(2) +C +Cf2py integer*4 :: n = 1 +Cf2py intent(out) l,u + integer*4 n,i + real*8 l(2),u(2),t,t1,t2,t3,t4 + l(2) = 1 + l(1) = 0 + u(2) = 0 + u(1) = 1 + do 10 i=0,n + t1 = 4 + 32*(1+i)*i + t2 = 11 + (40+32*i)*i + t3 = 3 + (24+32*i)*i + t4 = 8 + 32*(1+i)*i + t = u(1) + u(1) = l(1)*t1 + t*t2 + l(1) = l(1)*t3 + t*t4 + t = u(2) + u(2) = l(2)*t1 + t*t2 + l(2) = l(2)*t3 + t*t4 + 10 continue + end diff --git a/numpy/f2py/doc/f2python9-final/src/examples/exp1mess.txt b/numpy/f2py/doc/f2python9-final/src/examples/exp1mess.txt new file mode 100644 index 000000000..ae1545718 --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/src/examples/exp1mess.txt @@ -0,0 +1,17 @@ +Reading fortran codes... + Reading file 'exp1.f' +Post-processing... + Block: foo + Block: exp1 +Creating 'Makefile-foo'... + Linker: ld ('GNU ld' 2.9.5) + Fortran compiler: f77 ('g77 2.x.x' 2.95.2) + C compiler: cc ('gcc 2.x.x' 2.95.2) +Building modules... + Building module "foo"... + Constructing wrapper function "exp1"... + l,u = exp1([n]) + Wrote C/API module "foo" to file "foomodule.c" + Documentation is saved to file "foomodule.tex" +Run GNU make to build shared modules: + gmake -f Makefile-<modulename> [test] diff --git a/numpy/f2py/doc/f2python9-final/src/examples/exp1session.txt b/numpy/f2py/doc/f2python9-final/src/examples/exp1session.txt new file mode 100644 index 000000000..9bec9198e --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/src/examples/exp1session.txt @@ -0,0 +1,20 @@ +>>> import foo,Numeric +>>> print foo.exp1.__doc__ +exp1 - Function signature: + l,u = exp1([n]) +Optional arguments: + n := 1 input int +Return objects: + l : rank-1 array('d') with bounds (2) + u : rank-1 array('d') with bounds (2) + +>>> l,u = foo.exp1() +>>> print l,u +[ 1264. 465.] [ 1457. 536.] +>>> print l[0]/l[1], u[0]/u[1]-l[0]/l[1] +2.71827956989 2.25856657199e-06 +>>> l,u = foo.exp1(2) +>>> print l,u +[ 517656. 190435.] [ 566827. 208524.] +>>> print l[0]/l[1], u[0]/u[1]-l[0]/l[1] +2.71828182845 1.36437527942e-11
\ No newline at end of file diff --git a/numpy/f2py/doc/f2python9-final/src/examples/foo.pyf b/numpy/f2py/doc/f2python9-final/src/examples/foo.pyf new file mode 100644 index 000000000..516bb292f --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/src/examples/foo.pyf @@ -0,0 +1,13 @@ +!%f90 -*- f90 -*- +python module foo + interface + subroutine exp1(l,u,n) + real*8 dimension(2) :: l + real*8 dimension(2) :: u + integer*4 :: n + end subroutine exp1 + end interface +end python module foo +! This file was auto-generated with f2py +! (version:2.298). +! See http://cens.ioc.ee/projects/f2py2e/ diff --git a/numpy/f2py/doc/f2python9-final/src/examples/foom.pyf b/numpy/f2py/doc/f2python9-final/src/examples/foom.pyf new file mode 100644 index 000000000..6392ebc95 --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/src/examples/foom.pyf @@ -0,0 +1,14 @@ +!%f90 -*- f90 -*- +python module foo + interface + subroutine exp1(l,u,n) + real*8 dimension(2) :: l + real*8 dimension(2) :: u + intent(out) l,u + integer*4 optional :: n = 1 + end subroutine exp1 + end interface +end python module foo +! This file was auto-generated with f2py +! (version:2.298) and modified by pearu. +! See http://cens.ioc.ee/projects/f2py2e/ diff --git a/numpy/f2py/doc/f2python9-final/structure.jpg b/numpy/f2py/doc/f2python9-final/structure.jpg Binary files differnew file mode 100644 index 000000000..9aa691339 --- /dev/null +++ b/numpy/f2py/doc/f2python9-final/structure.jpg diff --git a/numpy/f2py/doc/fortranobject.tex b/numpy/f2py/doc/fortranobject.tex new file mode 100644 index 000000000..dbb244cdd --- /dev/null +++ b/numpy/f2py/doc/fortranobject.tex @@ -0,0 +1,574 @@ +\documentclass{article} + +\headsep=0pt +\topmargin=0pt +\headheight=0pt +\oddsidemargin=0pt +\textwidth=6.5in +\textheight=9in + +\usepackage{xspace} +\usepackage{verbatim} +\newcommand{\fpy}{\texttt{f2py}\xspace} +\newcommand{\bs}{\symbol{`\\}} +\newcommand{\email}[1]{\special{html:<A href="mailto:#1">}\texttt{<#1>}\special{html:</A>}} +\title{\texttt{PyFortranObject} --- example usages} +\author{ +\large Pearu Peterson\\ +\small \email{pearu@cens.ioc.ee} +} + +\begin{document} + +\maketitle + +\special{html: Other formats of this document: +<A href=pyfobj.ps.gz>Gzipped PS</A>, +<A href=pyfobj.pdf>PDF</A> +} + +\tableofcontents + +\section{Introduction} +\label{sec:intro} + +Fortran language defines the following concepts that we would like to +access from Python: functions, subroutines, data in \texttt{COMMON} blocks, +F90 module functions and subroutines, F90 module data (both static and +allocatable arrays). + +In the following we shall assume that we know the signatures (full +specifications of routine arguments and variables) of these concepts +from their Fortran source codes. Now, in order to call or use them +from C, one needs to have pointers to the corresponding objects. The +pointers to Fortran 77 objects (routines, data in \texttt{COMMON} +blocks) are readily available to C codes (there are various sources +available about mixing Fortran 77 and C codes). On the other hand, F90 +module specifications are highly compiler dependent and sometimes it +is not even possible to access F90 module objects from C (at least, +not directly, see remark about MIPSPro 7 Compilers). But using some +tricks (described below), the pointers to F90 module objects can be +determined in runtime providing a compiler independent solution. + +To use Fortran objects from Python in unified manner, \fpy introduces +\texttt{PyFortranObject} to hold pointers of the Fortran objects and +the corresponing wrapper functions. In fact, \texttt{PyFortranObject} +does much more: it generates documentation strings in run-time (for +items in \texttt{COMMON} blocks and data in F90 modules), provides +methods for accessing Fortran data and for calling Fortran routines, +etc. + +\section{\texttt{PyFortranObject}} +\label{sec:pyfortobj} + +\texttt{PyFortranObject} is defined as follows +\begin{verbatim} +typedef struct { + PyObject_HEAD + int len; /* Number of attributes */ + FortranDataDef *defs; /* An array of FortranDataDef's */ + PyObject *dict; /* Fortran object attribute dictionary */ +} PyFortranObject; +\end{verbatim} +where \texttt{FortranDataDef} is +\begin{verbatim} +typedef struct { + char *name; /* attribute (array||routine) name */ + int rank; /* array rank, 0 for scalar, max is F2PY_MAX_DIMS, + || rank=-1 for Fortran routine */ + struct {int d[F2PY_MAX_DIMS];} dims; /* dimensions of the array, || not used */ + int type; /* PyArray_<type> || not used */ + char *data; /* pointer to array || Fortran routine */ + void (*func)(); /* initialization function for + allocatable arrays: + func(&rank,dims,set_ptr_func,name,len(name)) + || C/API wrapper for Fortran routine */ + char *doc; /* documentation string; only recommended + for routines. */ +} FortranDataDef; +\end{verbatim} +In the following we demonstrate typical usages of +\texttt{PyFortranObject}. Just relevant code fragments will be given. + + +\section{Fortran 77 subroutine} +\label{sec:f77subrout} + +Consider Fortran 77 subroutine +\begin{verbatim} +subroutine bar() +end +\end{verbatim} +The corresponding \texttt{PyFortranObject} is defined in C as follows: +\begin{verbatim} +static char doc_bar[] = "bar()"; +static PyObject *c_bar(PyObject *self, PyObject *args, + PyObject *keywds, void (*f2py_func)()) { + static char *capi_kwlist[] = {NULL}; + if (!PyArg_ParseTupleAndKeywords(args,keywds,"|:bar",capi_kwlist)) + return NULL; + (*f2py_func)(); + return Py_BuildValue(""); +} +extern void F_FUNC(bar,BAR)(); +static FortranDataDef f2py_routines_def[] = { + {"bar",-1, {-1}, 0, (char *)F_FUNC(bar,BAR),(void*)c_bar,doc_bar}, + {NULL} +}; +void initfoo() { + <snip> + d = PyModule_GetDict(m); + PyDict_SetItemString(d, f2py_routines_def[0].name, + PyFortranObject_NewAsAttr(&f2py_routines_def[0])); +} +\end{verbatim} +where CPP macro \texttt{F\_FUNC} defines how Fortran 77 routines are +seen in C. +In Python, Fortran subroutine \texttt{bar} is called as follows +\begin{verbatim} +>>> import foo +>>> foo.bar() +\end{verbatim} + +\section{Fortran 77 function} +\label{sec:f77func} +Consider Fortran 77 function +\begin{verbatim} +function bar() +complex bar +end +\end{verbatim} +The corresponding \texttt{PyFortranObject} is defined in C as in +previous example but with the following changes: +\begin{verbatim} +static char doc_bar[] = "bar = bar()"; +static PyObject *c_bar(PyObject *self, PyObject *args, + PyObject *keywds, void (*f2py_func)()) { + complex_float bar; + static char *capi_kwlist[] = {NULL}; + if (!PyArg_ParseTupleAndKeywords(args,keywds,"|:bar",capi_kwlist)) + return NULL; + (*f2py_func)(&bar); + return Py_BuildValue("O",pyobj_from_complex_float1(bar)); +} +extern void F_WRAPPEDFUNC(bar,BAR)(); +static FortranDataDef f2py_routines_def[] = { + {"bar",-1,{-1},0,(char *)F_WRAPPEDFUNC(bar,BAR),(void *)c_bar,doc_bar}, + {NULL} +}; +\end{verbatim} +where CPP macro \texttt{F\_WRAPPEDFUNC} gives the pointer to the following +Fortran 77 subroutine: +\begin{verbatim} +subroutine f2pywrapbar (barf2pywrap) +external bar +complex bar, barf2pywrap +barf2pywrap = bar() +end +\end{verbatim} +With these hooks, calling Fortran functions returning composed types +becomes platform/compiler independent. + + +\section{\texttt{COMMON} block data} +\label{sec:commondata} + +Consider Fortran 77 \texttt{COMMON} block +\begin{verbatim} +integer i +COMMON /bar/ i +\end{verbatim} +In order to access the variable \texttt{i} from Python, +\texttt{PyFortranObject} is defined as follows: +\begin{verbatim} +static FortranDataDef f2py_bar_def[] = { + {"i",0,{-1},PyArray_INT}, + {NULL} +}; +static void f2py_setup_bar(char *i) { + f2py_bar_def[0].data = i; +} +extern void F_FUNC(f2pyinitbar,F2PYINITBAR)(); +static void f2py_init_bar() { + F_FUNC(f2pyinitbar,F2PYINITBAR)(f2py_setup_bar); +} +void initfoo() { + <snip> + PyDict_SetItemString(d, "bar", PyFortranObject_New(f2py_bar_def,f2py_init_bar)); +} +\end{verbatim} +where auxiliary Fortran function \texttt{f2pyinitbar} is defined as follows +\begin{verbatim} +subroutine f2pyinitbar(setupfunc) +external setupfunc +integer i +common /bar/ i +call setupfunc(i) +end +\end{verbatim} +and it is called in \texttt{PyFortranObject\_New}. + + +\section{Fortran 90 module subroutine} +\label{sec:f90modsubrout} + +Consider +\begin{verbatim} +module fun + subroutine bar() + end subroutine bar +end module fun +\end{verbatim} +\texttt{PyFortranObject} is defined as follows +\begin{verbatim} +static char doc_fun_bar[] = "fun.bar()"; +static PyObject *c_fun_bar(PyObject *self, PyObject *args, + PyObject *keywds, void (*f2py_func)()) { + static char *kwlist[] = {NULL}; + if (!PyArg_ParseTupleAndKeywords(args,keywds,"",kwlist)) + return NULL; + (*f2py_func)(); + return Py_BuildValue(""); +} +static FortranDataDef f2py_fun_def[] = { + {"bar",-1,{-1},0,NULL,(void *)c_fun_bar,doc_fun_bar}, + {NULL} +}; +static void f2py_setup_fun(char *bar) { + f2py_fun_def[0].data = bar; +} +extern void F_FUNC(f2pyinitfun,F2PYINITFUN)(); +static void f2py_init_fun() { + F_FUNC(f2pyinitfun,F2PYINITFUN)(f2py_setup_fun); +} +void initfoo () { + <snip> + PyDict_SetItemString(d, "fun", PyFortranObject_New(f2py_fun_def,f2py_init_fun)); +} +\end{verbatim} +where auxiliary Fortran function \texttt{f2pyinitfun} is defined as +follows +\begin{verbatim} +subroutine f2pyinitfun(f2pysetupfunc) +use fun +external f2pysetupfunc +call f2pysetupfunc(bar) +end subroutine f2pyinitfun +\end{verbatim} +The following Python session demonstrates how to call Fortran 90 +module function \texttt{bar}: +\begin{verbatim} +>>> import foo +>>> foo.fun.bar() +\end{verbatim} + +\section{Fortran 90 module function} +\label{sec:f90modfunc} + +Consider +\begin{verbatim} +module fun + function bar() + complex bar + end subroutine bar +end module fun +\end{verbatim} +\texttt{PyFortranObject} is defined as follows +\begin{verbatim} +static char doc_fun_bar[] = "bar = fun.bar()"; +static PyObject *c_fun_bar(PyObject *self, PyObject *args, + PyObject *keywds, void (*f2py_func)()) { + complex_float bar; + static char *kwlist[] = {NULL}; + if (!PyArg_ParseTupleAndKeywords(args,keywds,"",kwlist)) + return NULL; + (*f2py_func)(&bar); + return Py_BuildValue("O",pyobj_from_complex_float1(bar)); +} +static FortranDataDef f2py_fun_def[] = { + {"bar",-1,{-1},0,NULL,(void *)c_fun_bar,doc_fun_bar}, + {NULL} +}; +static void f2py_setup_fun(char *bar) { + f2py_fun_def[0].data = bar; +} +extern void F_FUNC(f2pyinitfun,F2PYINITFUN)(); +static void f2py_init_fun() { + F_FUNC(f2pyinitfun,F2PYINITFUN)(f2py_setup_fun); +} +void initfoo() { + <snip> + PyDict_SetItemString(d, "fun", PyFortranObject_New(f2py_fun_def,f2py_init_fun)); +} +\end{verbatim} +where +\begin{verbatim} +subroutine f2pywrap_fun_bar (barf2pywrap) +use fun +complex barf2pywrap +barf2pywrap = bar() +end + +subroutine f2pyinitfun(f2pysetupfunc) +external f2pysetupfunc,f2pywrap_fun_bar +call f2pysetupfunc(f2pywrap_fun_bar) +end +\end{verbatim} + + +\section{Fortran 90 module data} +\label{sec:f90moddata} + +Consider +\begin{verbatim} +module fun + integer i +end module fun +\end{verbatim} +Then +\begin{verbatim} +static FortranDataDef f2py_fun_def[] = { + {"i",0,{-1},PyArray_INT}, + {NULL} +}; +static void f2py_setup_fun(char *i) { + f2py_fun_def[0].data = i; +} +extern void F_FUNC(f2pyinitfun,F2PYINITFUN)(); +static void f2py_init_fun() { + F_FUNC(f2pyinitfun,F2PYINITFUN)(f2py_setup_fun); +} +void initfoo () { + <snip> + PyDict_SetItemString(d, "fun", + PyFortranObject_New(f2py_fun_def,f2py_init_fun)); +} +\end{verbatim} +where +\begin{verbatim} +subroutine f2pyinitfun(f2pysetupfunc) +use fun +external f2pysetupfunc +call f2pysetupfunc(i) +end subroutine f2pyinitfun +\end{verbatim} +Example usage in Python: +\begin{verbatim} +>>> import foo +>>> foo.fun.i = 4 +\end{verbatim} + +\section{Fortran 90 module allocatable array} +\label{sec:f90modallocarr} + +Consider +\begin{verbatim} +module fun + real, allocatable :: r(:) +end module fun +\end{verbatim} +Then +\begin{verbatim} +static FortranDataDef f2py_fun_def[] = { + {"r",1,{-1},PyArray_FLOAT}, + {NULL} +}; +static void f2py_setup_fun(void (*r)()) { + f2py_fun_def[0].func = r; +} +extern void F_FUNC(f2pyinitfun,F2PYINITFUN)(); +static void f2py_init_fun() { + F_FUNC(f2pyinitfun,F2PYINITFUN)(f2py_setup_fun); +} +void initfoo () { + <snip> + PyDict_SetItemString(d, "fun", PyFortranObject_New(f2py_fun_def,f2py_init_fun)); +} +\end{verbatim} +where +\begin{verbatim} +subroutine f2py_fun_getdims_r(r,s,f2pysetdata) +use fun, only: d => r +external f2pysetdata +logical ns +integer s(*),r,i,j +ns = .FALSE. +if (allocated(d)) then + do i=1,r + if ((size(d,r-i+1).ne.s(i)).and.(s(i).ge.0)) then + ns = .TRUE. + end if + end do + if (ns) then + deallocate(d) + end if +end if +if ((.not.allocated(d)).and.(s(1).ge.1)) then + allocate(d(s(1))) +end if +if (allocated(d)) then + do i=1,r + s(i) = size(d,r-i+1) + end do +end if +call f2pysetdata(d,allocated(d)) +end subroutine f2py_fun_getdims_r + +subroutine f2pyinitfun(f2pysetupfunc) +use fun +external f2pysetupfunc,f2py_fun_getdims_r +call f2pysetupfunc(f2py_fun_getdims_r) +end subroutine f2pyinitfun +\end{verbatim} +Usage in Python: +\begin{verbatim} +>>> import foo +>>> foo.fun.r = [1,2,3,4] +\end{verbatim} + +\section{Callback subroutine} +\label{sec:cbsubr} + +Thanks to Travis Oliphant for working out the basic idea of the +following callback mechanism. + +Consider +\begin{verbatim} +subroutine fun(bar) +external bar +call bar(1) +end +\end{verbatim} +Then +\begin{verbatim} +static char doc_foo8_fun[] = " +Function signature: + fun(bar,[bar_extra_args]) +Required arguments: + bar : call-back function +Optional arguments: + bar_extra_args := () input tuple +Call-back functions: + def bar(e_1_e): return + Required arguments: + e_1_e : input int"; +static PyObject *foo8_fun(PyObject *capi_self, PyObject *capi_args, + PyObject *capi_keywds, void (*f2py_func)()) { + PyObject *capi_buildvalue = NULL; + PyObject *bar_capi = Py_None; + PyTupleObject *bar_xa_capi = NULL; + PyTupleObject *bar_args_capi = NULL; + jmp_buf bar_jmpbuf; + int bar_jmpbuf_flag = 0; + int bar_nofargs_capi = 0; + static char *capi_kwlist[] = {"bar","bar_extra_args",NULL}; + + if (!PyArg_ParseTupleAndKeywords(capi_args,capi_keywds,\ + "O!|O!:foo8.fun",\ + capi_kwlist,&PyFunction_Type,&bar_capi,&PyTuple_Type,&bar_xa_capi)) + goto capi_fail; + + bar_nofargs_capi = cb_bar_in_fun__user__routines_nofargs; + if (create_cb_arglist(bar_capi,bar_xa_capi,1,0, + &cb_bar_in_fun__user__routines_nofargs,&bar_args_capi)) { + if ((PyErr_Occurred())==NULL) + PyErr_SetString(foo8_error,"failed in processing argument list for call-back bar." ); + goto capi_fail; + } + + SWAP(bar_capi,cb_bar_in_fun__user__routines_capi,PyObject); + SWAP(bar_args_capi,cb_bar_in_fun__user__routines_args_capi,PyTupleObject); + memcpy(&bar_jmpbuf,&cb_bar_in_fun__user__routines_jmpbuf,sizeof(jmp_buf)); + bar_jmpbuf_flag = 1; + + if ((setjmp(cb_bar_in_fun__user__routines_jmpbuf))) { + if ((PyErr_Occurred())==NULL) + PyErr_SetString(foo8_error,"Failure of a callback function"); + goto capi_fail; + } else + (*f2py_func)(cb_bar_in_fun__user__routines); + + capi_buildvalue = Py_BuildValue(""); +capi_fail: + + if (bar_jmpbuf_flag) { + cb_bar_in_fun__user__routines_capi = bar_capi; + Py_DECREF(cb_bar_in_fun__user__routines_args_capi); + cb_bar_in_fun__user__routines_args_capi = bar_args_capi; + cb_bar_in_fun__user__routines_nofargs = bar_nofargs_capi; + memcpy(&cb_bar_in_fun__user__routines_jmpbuf,&bar_jmpbuf,sizeof(jmp_buf)); + bar_jmpbuf_flag = 0; + } + return capi_buildvalue; +} +extern void F_FUNC(fun,FUN)(); +static FortranDataDef f2py_routine_defs[] = { + {"fun",-1,{-1},0,(char *)F_FUNC(fun,FUN),(void *)foo8_fun,doc_foo8_fun}, + {NULL} +}; +void initfoo8 () { + <snip> + PyDict_SetItemString(d, f2py_routine_defs[0].name, + PyFortranObject_NewAsAttr(&f2py_routine_defs[0])); +} +\end{verbatim} +where +\begin{verbatim} +PyObject *cb_bar_in_fun__user__routines_capi = Py_None; +PyTupleObject *cb_bar_in_fun__user__routines_args_capi = NULL; +int cb_bar_in_fun__user__routines_nofargs = 0; +jmp_buf cb_bar_in_fun__user__routines_jmpbuf; +static void cb_bar_in_fun__user__routines (int *e_1_e_cb_capi) { + PyTupleObject *capi_arglist = cb_bar_in_fun__user__routines_args_capi; + PyObject *capi_return = NULL; + PyObject *capi_tmp = NULL; + int capi_j,capi_i = 0; + + int e_1_e=(*e_1_e_cb_capi); + if (capi_arglist == NULL) + goto capi_fail; + if (cb_bar_in_fun__user__routines_nofargs>capi_i) + if (PyTuple_SetItem((PyObject *)capi_arglist,capi_i++,pyobj_from_int1(e_1_e))) + goto capi_fail; + + capi_return = PyEval_CallObject(cb_bar_in_fun__user__routines_capi, + (PyObject *)capi_arglist); + + if (capi_return == NULL) + goto capi_fail; + if (capi_return == Py_None) { + Py_DECREF(capi_return); + capi_return = Py_BuildValue("()"); + } + else if (!PyTuple_Check(capi_return)) { + capi_tmp = capi_return; + capi_return = Py_BuildValue("(O)",capi_tmp); + Py_DECREF(capi_tmp); + } + capi_j = PyTuple_Size(capi_return); + capi_i = 0; + goto capi_return_pt; +capi_fail: + fprintf(stderr,"Call-back cb_bar_in_fun__user__routines failed.\n"); + Py_XDECREF(capi_return); + longjmp(cb_bar_in_fun__user__routines_jmpbuf,-1); +capi_return_pt: + ; +} +\end{verbatim} +Usage in Python: +\begin{verbatim} +>>> import foo8 as foo +>>> def bar(i): print 'In bar i=',i +... +>>> foo.fun(bar) +In bar i= 1 +\end{verbatim} + +\end{document} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: diff --git a/numpy/f2py/doc/index.html b/numpy/f2py/doc/index.html new file mode 100644 index 000000000..e162ed41a --- /dev/null +++ b/numpy/f2py/doc/index.html @@ -0,0 +1,264 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> +<HTML> +<HEAD> +<META name="Author" content="Pearu Peterson"> +<!-- You may add here some keywords (comma separeted list) --> +<META name="Keywords" content="fortran,python,interface,f2py,f2py2e,wrapper,fpig"> +<TITLE>F2PY - Fortran to Python Interface Generator</TITLE> +<LINK rel="stylesheet" type="text/css" href="/styles/userstyle.css"> +</HEAD> + +<BODY> +<!-- Begin of user text --> +<H1>F2PY ­ Fortran to Python Interface Generator</H1> +by <em>Pearu Peterson</em> + +<h2>What's new?</h2> + +See <a href="NEWS.txt">NEWS.txt</a> for the latest changes in <code>f2py</code>. +<dl> + <dt> July ??, 2002 + <dd> Implemented prototype calculator, complete tests for scalar F77 + functions, --help-compiler option. Fixed number of bugs and + removed obsolete features. + <dt> April 4, 2002 + <dd> Fixed a nasty bug of copying one-dimensional non-contiguous arrays. + (Thanks to Travis O. for pointing this out). + <dt> March 26, 2002 + <dd> Bug fixes, turned off F2PY_REPORT_ATEXIT by default. + <dt> March 13, 2002 + <dd> MAC support, fixed incomplete dependency calculator, minor bug fixes. + <dt> March 3, 2002 + <dd> Fixed memory leak and copying of multi-dimensional complex arrays. + <dt> <a href="oldnews.html">Old news</a>. +</dl> + +<h2>Introduction</h2> + +Writing Python C/API wrappers for Fortran routines can be a very +tedious task, especially if a Fortran routine takes more than 20 +arguments but only few of them are relevant for the problems that they +solve. So, I have developed a tool that generates the C/API modules +containing wrapper functions of Fortran routines. I call this +tool as <em>F2PY ­ Fortran to Python Interface Generator</em>. +It is completely written in <a href="http://www.python.org">Python</a> +language and can be called from the command line as <code>f2py</code>. +<em>F2PY</em> (in NumPy) is released under the terms of the NumPy License. + + +<h2><code>f2py</code>, Second Edition</h2> + +The development of <code>f2py</code> started in summer of 1999. +For now (January, 2000) it has reached to stage of being a +complete tool: it scans real Fortran code, creates signature file +that the user can modify, constructs C/API module that can be +complied and imported to Python, and it creates LaTeX documentation +for wrapper functions. Below is a bit longer list of +<code>f2py</code> features: +<ol> + <li> <code>f2py</code> scans real Fortran codes and produces the signature files. + The syntax of the signature files is borrowed from the Fortran 90/95 + language specification with some extensions. + <li> <code>f2py</code> generates a GNU Makefile that can be used + for building shared modules (see below for a list of supported + platforms/compilers). Starting from the third release, + <code>f2py</code> generates <code>setup_modulename.py</code> for + building extension modules using <code>distutils</code> tools. + <li> <code>f2py</code> uses the signature files to produce the wrappers for + Fortran 77 routines and their <code>COMMON</code> blocks. + <li> For <code>external</code> arguments <code>f2py</code> constructs a very flexible + call-back mechanism so that Python functions can be called from + Fortran. + <li> You can pass in almost arbitrary Python objects to wrapper + functions. If needed, <code>f2py</code> takes care of type-casting and + non-contiguous arrays. + <li> You can modify the signature files so that <code>f2py</code> will generate + wrapper functions with desired signatures. <code>depend()</code> + attribute is introduced to control the initialization order of the + variables. <code>f2py</code> introduces <code>intent(hide)</code> + attribute to remove + the particular argument from the argument list of the wrapper + function and <code>intent(c)</code> that is useful for wrapping C +libraries. In addition, <code>optional</code> and +<code>required</code> + attributes are introduced and employed. + <li> <code>f2py</code> supports almost all standard Fortran 77/90/95 constructs + and understands all basic Fortran types, including + (multi-dimensional, complex) arrays and character strings with + adjustable and assumed sizes/lengths. + <li> <code>f2py</code> generates a LaTeX document containing the + documentations of the wrapped functions (argument types, dimensions, + etc). The user can easily add some human readable text to the + documentation by inserting <code>note(<LaTeX text>)</code> attribute to + the definition of routine signatures. + <li> With <code>f2py</code> one can access also Fortran 90/95 + module subroutines from Python. +</ol> + +For more information, see the <a href="usersguide.html">User's +Guide</a> of the tool. Windows users should also take a look at +<a href="win32_notes.txt">f2py HOWTO for Win32</a> (its latest version +can be found <a +href="http://www.numpy.org/Members/eric/f2py_win32">here</a>). + +<h3>Requirements</h3> +<ol> + <li> You'll need <a + href="http://www.python.org/download/">Python</a> + (1.5.2 or later, 2.2 is recommended) to run <code>f2py</code> + (because it uses exchanged module <code>re</code>). + To build generated extension modules with distutils setup script, + you'll need Python 2.x. + <li> You'll need <a + href="http://sourceforge.net/project/?group_id=1369">Numerical + Python</a> + (version 13 or later, 20.3 is recommended) to compile + C/API modules (because they use function + <code>PyArray_FromDimsAndDataAndDescr</code>) +</ol> + +<h3>Download</h3> + +<dl> + <dt> User's Guide: + <dd> <a href="usersguide.html">usersguide.html</a>, + <a href="usersguide.pdf">usersguide.pdf</a>, + <a href="usersguide.ps.gz">usersguide.ps.gz</a>, + <a href="usersguide.dvi">usersguide.dvi</a>. + <dt> Snapshots of the fifth public release: + <dd> <a href="2.x">2.x</a>/<a href="2.x/F2PY-2-latest.tar.gz">F2PY-2-latest.tar.gz</a> + <dt> Snapshots of earlier releases: + <dd> <a href="rel-5.x">rel-5.x</a>, <a href="rel-4.x">rel-4.x</a>, + <a href="rel-3.x">rel-3.x</a>, + <a href="rel-2.x">rel-2.x</a>,<a href="rel-1.x">rel-1.x</a>, + <a href="rel-0.x">rel-0.x</a> +</dl> + +<h3>Installation</h3> + +Unpack the source file, change to directory <code>f2py-?-???</code> +and run <code>python setup.py install</code>. That's it! + +<h3>Platform/Compiler Related Notes</h3> + +<code>f2py</code> has been successfully tested on +<ul> + <li> Intel Linux (MD7.0,RH6.1,RH4.2,Debian woody), Athlon Linux (RH6.1), Alpha Linux (RH5.2,RH6.1) with <a +href="http://gcc.gnu.org/">gcc</a> (versions egcs-2.91.60,egcs-2.91.66, and 2.95.2). + <li> Intel Linux (MD7.0) with <a + href="http://www.psrv.com/index.html">Pacific-Sierra + Research</a> <a href="http://www.psrv.com/lnxf90.html">Personal + Linux VAST/f90 Fortran 90 compiler</a> (version V3.4N5). + <li> Intel Linux (RH6.1) with <a href="http://www.absoft.com/">Absoft F77/F90</a> compilers for Linux. + <li> IRIX64 with <a href="http://gcc.gnu.org/">gcc</a> (2.95.2) and <a +href="http://www.sgi.com/developers/devtools/languages/mipspro.html">MIPSpro +7 Compilers</a> (f77,f90,cc versions 7.30). + <li> Alpha Linux (RH5.2,RH6.1) with <a href="http://www.digital.com/fortran/linux/">Compaq Fortran </a> compiler (version V1.0-920). + <li> Linux with <a href="http://www.nag.co.uk/">NAGWare</a> Fortran + 95 compiler. + <li> <a href="http://developer.intel.com/software/products/compilers/f50/linux/"> + Intel(R) Fortran Compiler for Linux</a> + <li> Windows 2000 with <a href="http://www.mingw.org">mingw32</a>. +</ul> +<code>f2py</code> will probably run on other UN*X systems as +well. Additions to the list of platforms/compilers where +<code>f2py</code> has been successfully used are most welcome. +<P> +<em>Note:</em> +Using Compaq Fortran +compiler on Alpha Linux is succesful unless when +wrapping Fortran callback functions returning +<code>COMPLEX</code>. This applies also for IRIX64. +<P> +<em>Note:</em> +Fortran 90/95 module support is currently tested with Absoft F90, VAST/f90, Intel F90 compilers on Linux (MD7.0,Debian woody). + + +<h3><a name="f2py-users">Mailing list</a></h3> + +There is a mailing list <a +href="http://cens.ioc.ee/pipermail/f2py-users/">f2py-users</a> +available for the users of the <code>f2py</code> +program and it is open for discussion, questions, and answers. You can subscribe +the list <a href="http://cens.ioc.ee/mailman/listinfo/f2py-users">here</a>. + +<h3><a href="http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/">CVS Repository</a></h3> + +<code>f2py</code> is being developed under <a href="http://www.sourcegear.com/CVS">CVS</a> and those who are +interested in the really latest version of <code>f2py</code> (possibly +unstable) can get it from the repository as follows: +<ol> + <li> First you need to login (the password is <code>guest</code>): +<pre> +> cvs -d :pserver:anonymous@cens.ioc.ee:/home/cvs login +</pre> + <li> and then do the checkout: +<pre> +> cvs -z6 -d :pserver:anonymous@cens.ioc.ee:/home/cvs checkout f2py2e +</pre> + <li> In the directory <code>f2py2e</code> you can get the updates by hitting +<pre> +> cvs -z6 update -P -d +</pre> +</ol> +You can browse <code>f2py</code> CVS repository <a href="http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/">here</a>. + +<h2>Related sites</h2> + +<ol> + <li> <a href="http://pfdubois.com/numpy/" target="_top">Numerical Python</a>. + <li> <a href="http://pyfortran.sourceforge.net/" target="_top">Pyfort</a> -- The Python-Fortran connection tool. + <li> <a href="http://starship.python.net/crew/hinsen/scientific.html" target="_top">Scientific Python</a>. + <li> <a href="http://numpy.org/" target="_top">SciPy</a> -- Scientific tools for Python (includes Multipack). + <li> <a href="http://www.fortran.com/fortran/" target="_top">The Fortran Company</a>. + <li> <a href="http://www.j3-fortran.org/" target="_top">Fortran Standards</a>. + + <li> <a href="http://www.fortran.com/fortran/F77_std/rjcnf.html">American National Standard Programming Language FORTRAN ANSI(R) X3.9-1978</a> + <li> <a href="http://www.mathtools.net" target="_top">Mathtools.net</a> -- A technical computing portal for all scientific and engineering needs. + +</ol> + +<!-- End of user text --> +<HR> +<ADDRESS> +<A href="http://validator.w3.org/"><IMG border=0 align=right src="/icons/vh40.gif" alt="Valid HTML 4.0!" height=31 width=88></A> +<A href="http://cens.ioc.ee/~pearu/" target="_top">Pearu Peterson</A> +<A href="mailto:pearu(at)ioc.ee"><pearu(at)ioc.ee></A><BR> +<!-- hhmts start --> +Last modified: Fri Jan 20 14:55:12 MST 2006 +<!-- hhmts end --> +</ADDRESS> +<!-- You may want to comment the following line out when the document is final--> +<!-- Check that the reference is right --> +<!--A href="http://validator.w3.org/check?uri=http://cens.ioc.ee/projects/f2py2e/index.html;ss"> Submit this page for validation</A--> + +<p> +<center> +This <a href="http://www.ctv.es/USERS/irmina/pythonring.html">Python +ring</a> site owned by <a href="mailto:pearu(at)ioc.ee">Pearu Peterson</a>. +<br> +[ + <a href="http://nav.webring.org/cgi-bin/navcgi?ring=python_ring;id=12;prev5">Previous 5 Sites</a> +| + <a href="http://nav.webring.org/cgi-bin/navcgi?ring=python_ring;id=12;prev">Previous</a> +| + <a href="http://nav.webring.org/cgi-bin/navcgi?ring=python_ring;id=12;next">Next</a> +| + <a href="http://nav.webring.org/cgi-bin/navcgi?ring=python_ring;id=12;next5">Next 5 Sites</a> +| + <a href="http://nav.webring.org/cgi-bin/navcgi?ring=python_ring;random">Random Site</a> +| + <a href="http://nav.webring.org/cgi-bin/navcgi?ring=python_ring;list">List Sites</a> +] +</center> +<p> + + + +</BODY> + + +</HTML> + + + diff --git a/numpy/f2py/doc/intro.tex b/numpy/f2py/doc/intro.tex new file mode 100644 index 000000000..d9625b09c --- /dev/null +++ b/numpy/f2py/doc/intro.tex @@ -0,0 +1,158 @@ + +\section{Introduction} +\label{sec:intro} + +\fpy is a command line tool that generates Python C/API modules for +interfacing Fortran~77/90/95 codes and Fortran~90/95 modules from +Python. In general, using \fpy an +interface is produced in three steps: +\begin{itemize} +\item[(i)] \fpy scans Fortran sources and creates the so-called + \emph{signature} file; the signature file contains the signatures of + Fortran routines; the signatures are given in the free format of the + Fortran~90/95 language specification. Latest version of \fpy + generates also a make file for building shared module. + About currently supported compilers see the \fpy home page +\item[(ii)] Optionally, the signature files can be modified manually + in order to dictate how the Fortran routines should be called or + seemed from the Python environment. +\item[(iii)] \fpy reads the signature files and generates Python C/API + modules that can be compiled and imported to Python code. In + addition, a LaTeX document is generated that contains the + documentation of wrapped functions. +\end{itemize} +(Note that if you are satisfied with the default signature that \fpy +generates in step (i), all three steps can be covered with just +one call to \fpy --- by not specifying `\texttt{-h}' flag). +Latest versions of \fpy support so-called \fpy directive that allows +inserting various information about wrapping directly to Fortran +source code as comments (\texttt{<comment char>f2py <signature statement>}). + +The following diagram illustrates the usage of the tool: +\begin{verbatim} +! Fortran file foo.f: + subroutine foo(a) + integer a + a = a + 5 + end +\end{verbatim} +\begin{verbatim} +! Fortran file bar.f: + function bar(a,b) + integer a,b,bar + bar = a + b + end +\end{verbatim} +\begin{itemize} +\item[(i)] \shell{\fpy foo.f bar.f -m foobar -h foobar.pyf} +\end{itemize} +\begin{verbatim} +!%f90 +! Signature file: foobar.pyf +python module foobar ! in + interface ! in :foobar + subroutine foo(a) ! in :foobar:foo.f + integer intent(inout) :: a + end subroutine foo + function bar(a,b) ! in :foobar:bar.f + integer :: a + integer :: b + integer :: bar + end function bar + end interface +end python module foobar +\end{verbatim} +\begin{itemize} +\item[(ii)] Edit the signature file (here I made \texttt{foo}s + argument \texttt{a} to be \texttt{intent(inout)}, see + Sec.~\ref{sec:attributes}). +\item[(iii)] \shell{\fpy foobar.pyf} +\end{itemize} +\begin{verbatim} +/* Python C/API module: foobarmodule.c */ +... +\end{verbatim} +\begin{itemize} +\item[(iv)] \shell{make -f Makefile-foobar} +%\shell{gcc -shared -I/usr/include/python1.5/ foobarmodule.c\bs\\ +%foo.f bar.f -o foobarmodule.so} +\end{itemize} +\begin{verbatim} +Python shared module: foobarmodule.so +\end{verbatim} +\begin{itemize} +\item[(v)] Usage in Python: +\end{itemize} +\vspace*{-4ex} +\begin{verbatim} +>>> import foobar +>>> print foobar.__doc__ +This module 'foobar' is auto-generated with f2py (version:1.174). +The following functions are available: + foo(a) + bar = bar(a,b) +. +>>> print foobar.bar(2,3) +5 +>>> from Numeric import * +>>> a = array(3) +>>> print a,foobar.foo(a),a +3 None 8 +\end{verbatim} +Information about how to call \fpy (steps (i) and (iii)) can be +obtained by executing\\ +\shell{\fpy}\\ +This will print the usage instructions. + Step (iv) is system dependent +(compiler and the locations of the header files \texttt{Python.h} and +\texttt{arrayobject.h}), and so you must know how to compile a shared +module for Python in you system. + +The next Section describes the step (ii) in more detail in order to +explain how you can influence to the process of interface generation +so that the users can enjoy more writing Python programs using your +wrappers that call Fortran routines. Step (v) is covered in +Sec.~\ref{sec:notes}. + + +\subsection{Features} +\label{sec:features} + +\fpy has the following features: +\begin{enumerate} +\item \fpy scans real Fortran codes and produces the signature files. + The syntax of the signature files is borrowed from the Fortran~90/95 + language specification with some extensions. +\item \fpy uses the signature files to produce the wrappers for + Fortran~77 routines and their \texttt{COMMON} blocks. +\item For \texttt{external} arguments \fpy constructs a very flexible + call-back mechanism so that Python functions can be called from + Fortran. +\item You can pass in almost arbitrary Python objects to wrapper + functions. If needed, \fpy takes care of type-casting and + non-contiguous arrays. +\item You can modify the signature files so that \fpy will generate + wrapper functions with desired signatures. \texttt{depend()} + attribute is introduced to control the initialization order of the + variables. \fpy introduces \texttt{intent(hide)} attribute to remove + the particular argument from the argument list of the wrapper + function. In addition, \texttt{optional} and \texttt{required} + attributes are introduced and employed. +\item \fpy supports almost all standard Fortran~77/90/95 constructs + and understands all basic Fortran types, including + (multi-dimensional, complex) arrays and character strings with + adjustable and assumed sizes/lengths. +\item \fpy generates a LaTeX document containing the + documentations of the wrapped functions (argument types, dimensions, + etc). The user can easily add some human readable text to the + documentation by inserting \texttt{note(<LaTeX text>)} attribute to + the definition of routine signatures. +\item \fpy generates a GNU make file that can be used for building + shared modules calling Fortran functions. +\item \fpy supports wrapping Fortran 90/95 module routines. +\end{enumerate} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "f2py2e" +%%% End: diff --git a/numpy/f2py/doc/multiarray/array_from_pyobj.c b/numpy/f2py/doc/multiarray/array_from_pyobj.c new file mode 100644 index 000000000..7e0de9a74 --- /dev/null +++ b/numpy/f2py/doc/multiarray/array_from_pyobj.c @@ -0,0 +1,323 @@ +/* + * File: array_from_pyobj.c + * + * Description: + * ------------ + * Provides array_from_pyobj function that returns a contigious array + * object with the given dimensions and required storage order, either + * in row-major (C) or column-major (Fortran) order. The function + * array_from_pyobj is very flexible about its Python object argument + * that can be any number, list, tuple, or array. + * + * array_from_pyobj is used in f2py generated Python extension + * modules. + * + * Author: Pearu Peterson <pearu@cens.ioc.ee> + * Created: 13-16 January 2002 + * $Id: array_from_pyobj.c,v 1.1 2002/01/16 18:57:33 pearu Exp $ + */ + + +#define ARR_IS_NULL(arr,mess) \ +if (arr==NULL) { \ + fprintf(stderr,"array_from_pyobj:" mess); \ + return NULL; \ +} + +#define CHECK_DIMS_DEFINED(rank,dims,mess) \ +if (count_nonpos(rank,dims)) { \ + fprintf(stderr,"array_from_pyobj:" mess); \ + return NULL; \ +} + +#define HAS_PROPER_ELSIZE(arr,type_num) \ + ((PyArray_DescrFromType(type_num)->elsize) == (arr)->descr->elsize) + +/* static */ +/* void f2py_show_args(const int type_num, */ +/* const int *dims, */ +/* const int rank, */ +/* const int intent) { */ +/* int i; */ +/* fprintf(stderr,"array_from_pyobj:\n\ttype_num=%d\n\trank=%d\n\tintent=%d\n",\ */ +/* type_num,rank,intent); */ +/* for (i=0;i<rank;++i) */ +/* fprintf(stderr,"\tdims[%d]=%d\n",i,dims[i]); */ +/* } */ + +static +int count_nonpos(const int rank, + const int *dims) { + int i=0,r=0; + while (i<rank) { + if (dims[i] <= 0) ++r; + ++i; + } + return r; +} + +static void lazy_transpose(PyArrayObject* arr); +static int check_and_fix_dimensions(const PyArrayObject* arr, + const int rank, + int *dims); +static +int array_has_column_major_storage(const PyArrayObject *ap); + +static +PyArrayObject* array_from_pyobj(const int type_num, + int *dims, + const int rank, + const int intent, + PyObject *obj) { + /* Note about reference counting + ----------------------------- + If the caller returns the array to Python, it must be done with + Py_BuildValue("N",arr). + Otherwise, if obj!=arr then the caller must call Py_DECREF(arr). + */ + +/* f2py_show_args(type_num,dims,rank,intent); */ + + if (intent & F2PY_INTENT_CACHE) { + /* Don't expect correct storage order or anything reasonable when + returning cache array. */ + if ((intent & F2PY_INTENT_HIDE) + || (obj==Py_None)) { + PyArrayObject *arr = NULL; + CHECK_DIMS_DEFINED(rank,dims,"optional,intent(cache) must" + " have defined dimensions.\n"); + arr = (PyArrayObject *)PyArray_FromDims(rank,dims,type_num); + ARR_IS_NULL(arr,"FromDims failed: optional,intent(cache)\n"); + if (intent & F2PY_INTENT_OUT) + Py_INCREF(arr); + return arr; + } + if (PyArray_Check(obj) + && ISCONTIGUOUS((PyArrayObject *)obj) + && HAS_PROPER_ELSIZE((PyArrayObject *)obj,type_num) + ) { + if (check_and_fix_dimensions((PyArrayObject *)obj,rank,dims)) + return NULL; /*XXX: set exception */ + if (intent & F2PY_INTENT_OUT) + Py_INCREF(obj); + return (PyArrayObject *)obj; + } + ARR_IS_NULL(NULL,"intent(cache) must be contiguous array with a proper elsize.\n"); + } + + if (intent & F2PY_INTENT_HIDE) { + PyArrayObject *arr = NULL; + CHECK_DIMS_DEFINED(rank,dims,"intent(hide) must have defined dimensions.\n"); + arr = (PyArrayObject *)PyArray_FromDims(rank,dims,type_num); + ARR_IS_NULL(arr,"FromDims failed: intent(hide)\n"); + if (intent & F2PY_INTENT_OUT) { + if ((!(intent & F2PY_INTENT_C)) && (rank>1)) { + lazy_transpose(arr); + arr->flags &= ~CONTIGUOUS; + } + Py_INCREF(arr); + } + return arr; + } + + if (PyArray_Check(obj)) { /* here we have always intent(in) or + intent(inout) */ + + PyArrayObject *arr = (PyArrayObject *)obj; + int is_cont = (intent & F2PY_INTENT_C) ? + (ISCONTIGUOUS(arr)) : (array_has_column_major_storage(arr)); + + if (check_and_fix_dimensions(arr,rank,dims)) + return NULL; /*XXX: set exception */ + + if ((intent & F2PY_INTENT_COPY) + || (! (is_cont + && HAS_PROPER_ELSIZE(arr,type_num) + && PyArray_CanCastSafely(arr->descr->type_num,type_num)))) { + PyArrayObject *tmp_arr = NULL; + if (intent & F2PY_INTENT_INOUT) { + ARR_IS_NULL(NULL,"intent(inout) array must be contiguous and" + " with a proper type and size.\n") + } + if ((rank>1) && (! (intent & F2PY_INTENT_C))) + lazy_transpose(arr); + if (PyArray_CanCastSafely(arr->descr->type_num,type_num)) { + tmp_arr = (PyArrayObject *)PyArray_CopyFromObject(obj,type_num,0,0); + ARR_IS_NULL(arr,"CopyFromObject failed: array.\n"); + } else { + tmp_arr = (PyArrayObject *)PyArray_FromDims(arr->nd, + arr->dimensions, + type_num); + ARR_IS_NULL(tmp_arr,"FromDims failed: array with unsafe cast.\n"); + if (copy_ND_array(arr,tmp_arr)) + ARR_IS_NULL(NULL,"copy_ND_array failed: array with unsafe cast.\n"); + } + if ((rank>1) && (! (intent & F2PY_INTENT_C))) { + lazy_transpose(arr); + lazy_transpose(tmp_arr); + tmp_arr->flags &= ~CONTIGUOUS; + } + arr = tmp_arr; + } + if (intent & F2PY_INTENT_OUT) + Py_INCREF(arr); + return arr; + } + + if ((obj==Py_None) && (intent & F2PY_OPTIONAL)) { + PyArrayObject *arr = NULL; + CHECK_DIMS_DEFINED(rank,dims,"optional must have defined dimensions.\n"); + arr = (PyArrayObject *)PyArray_FromDims(rank,dims,type_num); + ARR_IS_NULL(arr,"FromDims failed: optional.\n"); + if (intent & F2PY_INTENT_OUT) { + if ((!(intent & F2PY_INTENT_C)) && (rank>1)) { + lazy_transpose(arr); + arr->flags &= ~CONTIGUOUS; + } + Py_INCREF(arr); + } + return arr; + } + + if (intent & F2PY_INTENT_INOUT) { + ARR_IS_NULL(NULL,"intent(inout) argument must be an array.\n"); + } + + { + PyArrayObject *arr = (PyArrayObject *) \ + PyArray_ContiguousFromObject(obj,type_num,0,0); + ARR_IS_NULL(arr,"ContiguousFromObject failed: not a sequence.\n"); + if (check_and_fix_dimensions(arr,rank,dims)) + return NULL; /*XXX: set exception */ + if ((rank>1) && (! (intent & F2PY_INTENT_C))) { + PyArrayObject *tmp_arr = NULL; + lazy_transpose(arr); + arr->flags &= ~CONTIGUOUS; + tmp_arr = (PyArrayObject *) PyArray_CopyFromObject((PyObject *)arr,type_num,0,0); + Py_DECREF(arr); + arr = tmp_arr; + ARR_IS_NULL(arr,"CopyFromObject(Array) failed: intent(fortran)\n"); + lazy_transpose(arr); + arr->flags &= ~CONTIGUOUS; + } + if (intent & F2PY_INTENT_OUT) + Py_INCREF(arr); + return arr; + } + +} + + /*****************************************/ + /* Helper functions for array_from_pyobj */ + /*****************************************/ + +static +int array_has_column_major_storage(const PyArrayObject *ap) { + /* array_has_column_major_storage(a) is equivalent to + transpose(a).iscontiguous() but more efficient. + + This function can be used in order to decide whether to use a + Fortran or C version of a wrapped function. This is relevant, for + example, in choosing a clapack or flapack function depending on + the storage order of array arguments. + */ + int sd; + int i; + sd = ap->descr->elsize; + for (i=0;i<ap->nd;++i) { + if (ap->dimensions[i] == 0) return 1; + if (ap->strides[i] != sd) return 0; + sd *= ap->dimensions[i]; + } + return 1; +} + +static +void lazy_transpose(PyArrayObject* arr) { + /* + Changes the order of array strides and dimensions. This + corresponds to the lazy transpose of a Numeric array in-situ. + Note that this function is assumed to be used even times for a + given array. Otherwise, the caller should set flags &= ~CONTIGUOUS. + */ + int rank,i,s,j; + rank = arr->nd; + if (rank < 2) return; + + for(i=0,j=rank-1;i<rank/2;++i,--j) { + s = arr->strides[i]; + arr->strides[i] = arr->strides[j]; + arr->strides[j] = s; + s = arr->dimensions[i]; + arr->dimensions[i] = arr->dimensions[j]; + arr->dimensions[j] = s; + } +} + +static +int check_and_fix_dimensions(const PyArrayObject* arr,const int rank,int *dims) { + /* + This function fills in blanks (that are -1's) in dims list using + the dimensions from arr. It also checks that non-blank dims will + match with the corresponding values in arr dimensions. + */ + const int arr_size = (arr->nd)?PyArray_Size((PyObject *)arr):1; + + if (rank > arr->nd) { /* [1,2] -> [[1],[2]]; 1 -> [[1]] */ + int new_size = 1; + int free_axe = -1; + int i; + /* Fill dims where -1 or 0; check dimensions; calc new_size; */ + for(i=0;i<arr->nd;++i) { + if (dims[i] >= 0) { + if (dims[i]!=arr->dimensions[i]) { + fprintf(stderr,"%d-th dimension must be fixed to %d but got %d\n", + i,dims[i],arr->dimensions[i]); + return 1; + } + if (!dims[i]) dims[i] = 1; + } else { + dims[i] = arr->dimensions[i] ? arr->dimensions[i] : 1; + } + new_size *= dims[i]; + } + for(i=arr->nd;i<rank;++i) + if (dims[i]>1) { + fprintf(stderr,"%d-th dimension must be %d but got 0 (not defined).\n", + i,dims[i]); + return 1; + } else if (free_axe<0) + free_axe = i; + else + dims[i] = 1; + if (free_axe>=0) { + dims[free_axe] = arr_size/new_size; + new_size *= dims[free_axe]; + } + if (new_size != arr_size) { + fprintf(stderr,"confused: new_size=%d, arr_size=%d (maybe too many free" + " indices)\n",new_size,arr_size); + return 1; + } + } else { + int i; + for (i=rank;i<arr->nd;++i) + if (arr->dimensions[i]>1) { + fprintf(stderr,"too many axes: %d, expected rank=%d\n",arr->nd,rank); + return 1; + } + for (i=0;i<rank;++i) + if (dims[i]>=0) { + if (arr->dimensions[i]!=dims[i]) { + fprintf(stderr,"%d-th dimension must be fixed to %d but got %d\n", + i,dims[i],arr->dimensions[i]); + return 1; + } + if (!dims[i]) dims[i] = 1; + } else + dims[i] = arr->dimensions[i]; + } + return 0; +} + +/* End of file: array_from_pyobj.c */ diff --git a/numpy/f2py/doc/multiarray/bar.c b/numpy/f2py/doc/multiarray/bar.c new file mode 100644 index 000000000..350636ea6 --- /dev/null +++ b/numpy/f2py/doc/multiarray/bar.c @@ -0,0 +1,15 @@ + +#include <stdio.h> + +void bar(int *a,int m,int n) { + int i,j; + printf("C:"); + printf("m=%d, n=%d\n",m,n); + for (i=0;i<m;++i) { + printf("Row %d:\n",i+1); + for (j=0;j<n;++j) + printf("a(i=%d,j=%d)=%d\n",i,j,a[n*i+j]); + } + if (m*n) + a[0] = 7777; +} diff --git a/numpy/f2py/doc/multiarray/foo.f b/numpy/f2py/doc/multiarray/foo.f new file mode 100644 index 000000000..f8c39c4d1 --- /dev/null +++ b/numpy/f2py/doc/multiarray/foo.f @@ -0,0 +1,13 @@ + subroutine foo(a,m,n) + integer a(m,n), m,n,i,j + print*, "F77:" + print*, "m=",m,", n=",n + do 100,i=1,m + print*, "Row ",i,":" + do 50,j=1,n + print*, "a(i=",i,",j=",j,") = ",a(i,j) + 50 continue + 100 continue + if (m*n.gt.0) a(1,1) = 77777 + end + diff --git a/numpy/f2py/doc/multiarray/fortran_array_from_pyobj.txt b/numpy/f2py/doc/multiarray/fortran_array_from_pyobj.txt new file mode 100644 index 000000000..c7b945c84 --- /dev/null +++ b/numpy/f2py/doc/multiarray/fortran_array_from_pyobj.txt @@ -0,0 +1,284 @@ + + _____________________________________________________________ + / Proposed internal structure for f2py generated extension \ + < modules regarding the issues with different storage-orders > + \ of multi-dimensional matrices in Fortran and C. / + ============================================================= + +Author: Pearu Peterson +Date: 14 January, 2001 + +Definitions: +============ + +In the following I will use the following definitions: + +1) A matrix is a mathematical object that represents a collection of + objects (elements), usually visualized in a table form, and one can + define a set of various (algebraic,etc) operations for matrices. + One can think of a matrix as a defintion of a certain mapping: + (i) |--> A(i) + where i belongs to the set of indices (an index itself can be a + sequence of objects, for example, a sequence of integers) and A(i) + is an element from a specified set, for example, a set of fruits. + Symbol A then denotes a matrix of fruits. + +2) An array is a storage object that represents a collection of + objects stored in a certain systematic way, for example, as an + ordered sequence in computer memory. + +In order to manipulate matrices using computers, one must store matrix +elements in computer memory. In the following, I will assume that the +elements of a matrix is stored as an array. There is no unique way in +which order one should save matrix elements in the array. However, in +C and Fortran programming languages, two, unfortunately different, +conventions are used. + +Aim: +==== + +The purpose of this writing is to work out an interface for Python +language so that C and Fortran routines can be called without +bothering about how multi-dimensional matrices are stored in memory. +For example, accessing a matrix element A[i,j] in Python will be +equivalent to accessing the same matrix in C, using A[i][j], or in +Fortran, using A(i,j). + +External conditions: +==================== + +In C programming language, it is custom to think that matrices are +stored in the so-called row-major order, that is, a matrix is stored +row by row, each row is as a contiguous array in computer memory. + +In Fortran programming language, matrices are stored in the +column-major order: each column is a contiguous array in computer +memory. + +In Python programming language, matrices can be stored using Python +Numeric array() function that uses internally C approach, that is, +elements of matrices are stored in row-major order. For example, +A = array([[1,2,3],[4,5,6]]) represents a 2-by-3 matrix + + / 1 2 3 \ + | | + \ 4 5 6 / + +and its elements are stored in computer memory as the following array: + + 1 2 3 4 5 6 + +The same matrix, if used in Fortran, would be stored in computer +memory as the following array: + + 1 4 2 5 3 6 + +Problem and solution: +===================== + +A problem arises if one wants to use the same matrix both in C and in +Fortran functions. Then the difference in storage order of a matrix +elements must be taken into account. This technical detail can be very +confusing even for an experienced programmer. This is because when +passing a matrix to a Fortran subroutine, you must (mentally or +programmically) transpose the matrix and when the subroutine returns, +you must transpose it back. + +As will be discussed below, there is a way to overcome these +difficulties in Python by creating an interface between Python and +Fortran code layers that takes care of this transition internally. So +that if you will read the manual pages of the Fortran codes, then you +need not to think about how matrices are actually stored, the storage +order will be the same, seemingly. + +Python / C / Fortran interface: +=============================== + +The interface between Python and Fortran codes will use the following +Python Numeric feature: transposing a Numeric array does not involve +copying of its data but just permuting the dimensions and strides of +the array (the so-called lazy transpose). + +However, when passing a Numeric array data pointer to Fortran or C +function, the data must be contiguous in memory. If it is not, then +data is rearranged inplace. I don't think that it can be avoided. +This is certainly a penalty hit to performance. However, one can +easily avoid it by creating a Numeric array with the right storage +order, so that after transposing, the array data will be contiguous in +memory and the data pointer can safely passed on to the Fortran +subroutine. This lazy-transpose operation will be done within the +interface and users need not to bother about this detail anymore (that +is, after they initialize Numeric array with matrix elements using the +proper order. Of course, the proper order depends on the target +function: C or Fortran). The interface should be smart enough to +minimize the need of real-transpose operations and the need to +additional memory storage as well. + +Statement of the problem: +========================= + +Consider a M-by-N matrix A of integers, where M and N are the number A +rows and columns, respectively. + +In Fortran language, the storing array of this matrix can be defined +as follows: + + integer A(M,N) + +in C: + + int A[M][N]; + +and in Python: + + A = Numeric.zeros((M,N),'i') + +Consider also the corresponding Fortran and C functions that +that use matrix arguments: + +Fortran: + subroutine FUN(A,M,N) + integer A(M,N) + ... + end +C: + void cun(int *a,int m,int n) { + ... + } + +and the corresponding Python interface signatures: + + def py_fun(a): + ... + def py_cun(a): + ... + +Main goal: +========== + +Our goal is to generate Python C/API functions py_fun and py_cun such +that their usage in Python would be identical. The cruical part of +their implementation are in functions that take a PyObject and +return a PyArrayObject such that it is contiguous and its data pointer +is suitable for passing on to the arguments of C or Fortran functions. +The prototypes of these functions are: + +PyArrayObject* fortran_array_from_pyobj( + int typecode, + int *dims, + int rank, + int intent, + PyObject *obj); + +and + +PyArrayObject* c_array_from_pyobj( + int typecode, + int *dims, + int rank, + int intent, + PyObject *obj); + +for wrapping Fortran and C functions, respectively. + +Pseudo-code for fortran_array_from_pyobj: +========================================= + +if type(obj) is ArrayType: + #raise not check(len(ravel(obj)) >= dims[0]*dims[1]*...*dims[rank-1]) + if obj.typecode is typecode: + if is_contiguous(obj): + transpose_data_inplace(obj) # real-transpose + set_transpose_strides(obj) # lazy-transpose + Py_INCREF(obj); + return obj + set_transpose_strides(obj) + if is_contiguous(obj): + set_transpose_strides(obj) + Py_INCREF(obj); + return obj + else: + tmp_obj = PyArray_ContiguousFromObject(obj,typecode,0,0) + swap_datapointer_and_typeinfo(obj,tmp_obj) + Py_DECREF(tmp_obj); + set_transpose_strides(obj) + Py_INCREF(obj); + return obj + else: + tmp_obj = PyArray_FromDims(rank,dims,typecode) + set_transpose_strides(tmp_obj) + if intent in [in,inout]: + copy_ND_array(obj,tmp_obj) + swap_datapointer_and_typeinfo(obj,tmp_obj) + Py_DECREF(tmp_obj); + Py_INCREF(obj); + return obj +elif obj is None: # happens when only intent is 'hide' + tmp_obj = PyArray_FromDims(rank,dims,typecode) + if intent is out: + set_transpose_strides(tmp_obj) + # otherwise tmp_obj->data is used as a work array + Py_INCREF(tmp_obj) + return tmp_obj +else: + tmp_obj = PyArray_ContiguousFromObject(obj,typecode,0,0) + #raise not check(len(ravel(obj)) >= dims[0]*dims[1]*...*dims[rank-1]) + set_transpose_strides(tmp_obj) + transpose_data_inplace(tmp_obj) + Py_INCREF(tmp_obj) + return tmp_obj + +Notes: + 1) CPU expensive tasks are in transpose_data_inplace and + copy_ND_array, PyArray_ContiguousFromObject. + 2) Memory expensive tasks are in PyArray_FromDims, + PyArray_ContiguousFromObject + 3) Side-effects are expected when set_transpose_strides and + transpose_data_inplace are used. For example: + >>> a = Numeric([[1,2,3],[4,5,6]],'d') + >>> a.is_contiguous() + 1 + >>> py_fun(a) + >>> a.typecode() + 'i' + >>> a.is_contiguous() + 0 + >>> transpose(a).is_contiguous() + 1 + +Pseudo-code for c_array_from_pyobj: +=================================== + +if type(obj) is ArrayType: + #raise not check(len(ravel(obj)) >= dims[0]*dims[1]*...*dims[rank-1]) + if obj.typecode is typecode: + if is_contiguous(obj): + Py_INCREF(obj); + return obj + else: + tmp_obj = PyArray_ContiguousFromObject(obj,typecode,0,0) + swap_datapointer_and_typeinfo(obj,tmp_obj) + Py_DECREF(tmp_obj); + Py_INCREF(obj); + return obj + else: + tmp_obj = PyArray_FromDims(rank,dims,typecode) + if intent in [in,inout]: + copy_ND_array(obj,tmp_obj) + swap_datapointer_and_typeinfo(obj,tmp_obj) + Py_DECREF(tmp_obj); + Py_INCREF(obj); + return obj +elif obj is None: # happens when only intent is 'hide' + tmp_obj = PyArray_FromDims(rank,dims,typecode) + Py_INCREF(tmp_obj) + return tmp_obj +else: + tmp_obj = PyArray_ContiguousFromObject(obj,typecode,0,0) + #raise not check(len(ravel(obj)) >= dims[0]*dims[1]*...*dims[rank-1]) + Py_INCREF(tmp_obj) + return tmp_obj + + +14 January, 2002 +Pearu Peterson <pearu@cens.ioc.ee>
\ No newline at end of file diff --git a/numpy/f2py/doc/multiarray/fun.pyf b/numpy/f2py/doc/multiarray/fun.pyf new file mode 100644 index 000000000..ed5d1923f --- /dev/null +++ b/numpy/f2py/doc/multiarray/fun.pyf @@ -0,0 +1,89 @@ +!%f90 -*- f90 -*- + +! Example: +! Using f2py for wrapping multi-dimensional Fortran and C arrays +! [NEW APPROACH, use it with f2py higher than 2.8.x] +! $Id: fun.pyf,v 1.3 2002/01/18 10:06:50 pearu Exp $ + +! Usage (with gcc compiler): +! f2py -c fun.pyf foo.f bar.c + +python module fun ! in + interface ! in :fun + +! >>> from Numeric import * +! >>> import fun +! >>> a=array([[1,2,3],[4,5,6]]) + + subroutine foo(a,m,n) ! in :fun:foo.f + integer dimension(m,n) :: a + intent(in,out,copy) :: a + integer optional,check(shape(a,0)==m),depend(a) :: m=shape(a,0) + integer optional,check(shape(a,1)==n),depend(a) :: n=shape(a,1) + end subroutine foo + +! >>> print fun.foo.__doc__ +! foo - Function signature: +! a = foo(a,[m,n]) +! Required arguments: +! a : input rank-2 array('i') with bounds (m,n) +! Optional arguments: +! m := shape(a,0) input int +! n := shape(a,1) input int +! Return objects: +! a : rank-2 array('i') with bounds (m,n) + +! >>> print fun.foo(a) +! F77: +! m= 2, n= 3 +! Row 1: +! a(i= 1,j= 1) = 1 +! a(i= 1,j= 2) = 2 +! a(i= 1,j= 3) = 3 +! Row 2: +! a(i= 2,j= 1) = 4 +! a(i= 2,j= 2) = 5 +! a(i= 2,j= 3) = 6 +! [[77777 2 3] +! [ 4 5 6]] + + + subroutine bar(a,m,n) + intent(c) + intent(c) bar + integer dimension(m,n) :: a + intent(in,out) :: a + integer optional,check(shape(a,0)==m),depend(a) :: m=shape(a,0) + integer optional,check(shape(a,1)==n),depend(a) :: n=shape(a,1) + intent(in) m,n + end subroutine bar + +! >>> print fun.bar.__doc__ +! bar - Function signature: +! a = bar(a,[m,n]) +! Required arguments: +! a : input rank-2 array('i') with bounds (m,n) +! Optional arguments: +! m := shape(a,0) input int +! n := shape(a,1) input int +! Return objects: +! a : rank-2 array('i') with bounds (m,n) + +! >>> print fun.bar(a) +! C:m=2, n=3 +! Row 1: +! a(i=0,j=0)=1 +! a(i=0,j=1)=2 +! a(i=0,j=2)=3 +! Row 2: +! a(i=1,j=0)=4 +! a(i=1,j=1)=5 +! a(i=1,j=2)=6 +! [[7777 2 3] +! [ 4 5 6]] + + end interface +end python module fun + +! This file was auto-generated with f2py (version:2.9.166). +! See http://cens.ioc.ee/projects/f2py2e/ diff --git a/numpy/f2py/doc/multiarray/run.pyf b/numpy/f2py/doc/multiarray/run.pyf new file mode 100644 index 000000000..bb12a439b --- /dev/null +++ b/numpy/f2py/doc/multiarray/run.pyf @@ -0,0 +1,91 @@ +!%f90 -*- f90 -*- + +! Example: +! Using f2py for wrapping multi-dimensional Fortran and C arrays +! [OLD APPROACH, do not use it with f2py higher than 2.8.x] +! $Id: run.pyf,v 1.1 2002/01/14 15:49:46 pearu Exp $ + +! Usage (with gcc compiler): +! f2py -c run.pyf foo.f bar.c -DNO_APPEND_FORTRAN + +python module run ! in + interface ! in :run + +! >>> from Numeric import * +! >>> import run +! >>> a=array([[1,2,3],[4,5,6]],'i') + + subroutine foo(a,m,n) + fortranname foo_ + integer dimension(m,n) :: a + integer optional,check(shape(a,1)==m),depend(a) :: m=shape(a,1) + integer optional,check(shape(a,0)==n),depend(a) :: n=shape(a,0) + end subroutine foo + +! >>> print run.foo.__doc__ +! foo - Function signature: +! foo(a,[m,n]) +! Required arguments: +! a : input rank-2 array('i') with bounds (n,m) +! Optional arguments: +! m := shape(a,1) input int +! n := shape(a,0) input int + +! >>> run.foo(a) +! F77: +! m= 3, n= 2 +! Row 1: +! a(i= 1,j= 1) = 1 +! a(i= 1,j= 2) = 4 +! Row 2: +! a(i= 2,j= 1) = 2 +! a(i= 2,j= 2) = 5 +! Row 3: +! a(i= 3,j= 1) = 3 +! a(i= 3,j= 2) = 6 + +! >>> run.foo(transpose(a)) +! F77: +! m= 2, n= 3 +! Row 1: +! a(i= 1,j= 1) = 1 +! a(i= 1,j= 2) = 2 +! a(i= 1,j= 3) = 3 +! Row 2: +! a(i= 2,j= 1) = 4 +! a(i= 2,j= 2) = 5 +! a(i= 2,j= 3) = 6 + + subroutine bar(a,m,n) + intent(c) + integer dimension(m,n) :: a + integer optional,check(shape(a,0)==m),depend(a) :: m=shape(a,0) + integer optional,check(shape(a,1)==n),depend(a) :: n=shape(a,1) + end subroutine bar + +! >>> print run.bar.__doc__ +! bar - Function signature: +! bar(a,[m,n]) +! Required arguments: +! a : rank-2 array('i') with bounds (m,n) +! Optional arguments: +! m := shape(a,0) int +! n := shape(a,1) int + +! >>> run.bar(a) +! C:m=2, n=3 +! Row 1: +! a(i=0,j=0)=1 +! a(i=0,j=1)=2 +! a(i=0,j=2)=3 +! Row 2: +! a(i=1,j=0)=4 +! a(i=1,j=1)=5 +! a(i=1,j=2)=6 + + + end interface +end python module run + +! This file was auto-generated with f2py (version:2.8.172). +! See http://cens.ioc.ee/projects/f2py2e/ diff --git a/numpy/f2py/doc/multiarray/transpose.txt b/numpy/f2py/doc/multiarray/transpose.txt new file mode 100644 index 000000000..a8d41e6df --- /dev/null +++ b/numpy/f2py/doc/multiarray/transpose.txt @@ -0,0 +1,1127 @@ +From: Phil Garner (garner@signal.dra.hmg.gb) + Subject: In place matrix transpose + Newsgroups: sci.math.num-analysis + Date: 1993-08-05 06:35:06 PST + + +Someone was talking about matrix transposes earlier on. It's a +curious subject. I found that an in-place transpose is about 12 times +slower than the trivial copying method. + +Here's somthing I nicked from netlib and translated into C to do the +in-place one for those that are interested: (matrix must be in one +block) + + +typedef float scalar; /* float -> double for double precision */ + +/* + * In Place Matrix Transpose + * From: Algorithm 380 collected algorithms from ACM. + * Converted to C by Phil Garner + * + * Algorithm appeared in comm. ACM, vol. 13, no. 05, + * p. 324. + */ +int trans(scalar *a, unsigned m, unsigned n, int *move, int iwrk) +{ + scalar b; + int i, j, k, i1, i2, ia, ib, ncount, kmi, Max, mn; + + /* + * a is a one-dimensional array of length mn=m*n, which + * contains the m by n matrix to be transposed. + * move is a one-dimensional array of length iwrk + * used to store information to speed up the process. the + * value iwrk=(m+n)/2 is recommended. Return val indicates the + * success or failure of the routine. + * normal return = 0 + * errors + * -2, iwrk negative or zero. + * ret > 0, (should never occur). in this case + * we set ret equal to the final value of i when the search + * is completed but some loops have not been moved. + * check arguments and initialise + */ + + /* Function Body */ + if (n < 2 || m < 2) + return 0; + if (iwrk < 1) + return -2; + + /* If matrix is square, exchange elements a(i,j) and a(j,i). */ + if (n == m) + { + for (i = 0; i < m - 1; ++i) + for (j = i + 1; j < m; ++j) + { + i1 = i + j * m; + i2 = j + i * m; + b = a[i1]; + a[i1] = a[i2]; + a[i2] = b; + } return 0; + } + + /* Non square matrix */ + ncount = 2; + for (i = 0; i < iwrk; ++i) + move[i] = 0; + + if (n > 2) + /* Count number,ncount, of single points. */ + for (ia = 1; ia < n - 1; ++ia) + { + ib = ia * (m - 1) / (n - 1); + if (ia * (m - 1) != ib * (n - 1)) + continue; + ++ncount; + i = ia * m + ib; + if (i > iwrk) + continue; + move[i] = 1; + } + + /* Set initial values for search. */ + mn = m * n; + k = mn - 1; + kmi = k - 1; + Max = mn; + i = 1; + + while (1) + { + /* Rearrange elements of a loop. */ + /* At least one loop must be re-arranged. */ + i1 = i; + while (1) + { + b = a[i1]; + while (1) + { + i2 = n * i1 - k * (i1 / m); + if (i1 <= iwrk) + move[i1 - 1] = 2; + ++ncount; + if (i2 == i || i2 >= kmi) + { + if (Max == kmi || i2 == i) + break; + Max = kmi; + } + a[i1] = a[i2]; + i1 = i2; + } + + /* Test for symmetric pair of loops. */ + a[i1] = b; + if (ncount >= mn) + return 0; + if (i2 == Max || Max == kmi) + break; + Max = kmi; + i1 = Max; + } + + /* Search for loops to be rearranged. */ + while (1) + { + Max = k - i; + ++i; + kmi = k - i; + if (i > Max) + return i; + if (i <= iwrk) + { + if (move[i-1] < 1) + break; + continue; + } + if (i == n * i - k * (i / m)) + continue; + i1 = i; + while (1) + { + i2 = n * i1 - k * (i1 / m); + if (i2 <= i || i2 >= Max) + break; + i1 = i2; + } + if (i2 == i) + break; + } + } /* End never reached */ +} + +-- + ,----------------------------- ______ + ____ | Phil Garner. \___| |/ \ \ ____ +/__/ `--, _L__L\_ | garner@signal.dra.hmg.gb | _|`---' \_/__/ `--, +`-0---0-' `-0--0-' `--OO-------------------O-----' `---0---' `-0---0-' + + From: Murray Dow (mld900@anusf.anu.edu.au) + Subject: Re: In place matrix transpose + Newsgroups: sci.math.num-analysis + Date: 1993-08-09 19:45:57 PST + + +In article <23qmp3INN3gl@mentor.dra.hmg.gb>, garner@signal.dra.hmg.gb (Phil Garner) writes: +|> Someone was talking about matrix transposes earlier on. It's a +|> curious subject. I found that an in-place transpose is about 12 times +|> slower than the trivial copying method. +|> + +Algorithm 380 from CACM is sloweer than ALG 467. Here are my times +from a VP2200 vector computer. Note that the CACM algorithms are scalar. +Times are in seconds, for a 900*904 matrix: + +380 NAG 467 disc copy +1.03 1.14 .391 .177 + +Compare two vector algortihms, one I wrote and the second a matrix +copy: + +My Alg Matrix copy +.0095 .0097 + +Conclusions: dont use Alg 380 from Netlib. If you have the available memory, +do a matrix copy. If you don't have the memory, I will send you my algorithm +when I have published it. +-- +Murray Dow GPO Box 4 Canberra ACT 2601 Australia +Supercomputer Facility Phone: +61 6 2495028 +Australian National University Fax: +61 6 2473425 +mld900@anusf.anu.edu.au + +============================================================================= + +From: Mark Smotherman (mark@hubcap.clemson.edu) + Subject: Matrix transpose benchmark [was Re: MIPS R8000 == TFP?] + Newsgroups: comp.arch, comp.benchmarks, comp.sys.super + Date: 1994-07-01 06:35:51 PST + + +mccalpin@perelandra.cms.udel.edu (John D. McCalpin) writes: + +> +>Of course, these results are all for the naive algorithm. I would be +>interested to see what an efficient blocked algorithm looks like. +>Anyone care to offer one? There is clearly a lot of performance +>to be gained by the effort.... + +Here is a matrix transpose benchmark generator. Enter something like + + 10d10eij; + +and you get a benchmark program with tiles of size 10 for the i and j +inner loops. Please email code improvements and flames. + +Enjoy! + + +/*--------------------------------------------------------------------------- + + Matrix Transpose Generator + + Copyright 1993, Dept. of Computer Science, Clemson University + + Permission to use, copy, modify, and distribute this software and + its documentation for any purpose and without fee is hereby granted, + provided that the above copyright notice appears in all copies. + + Clemson University and its Dept. of Computer Science make no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied warranty. + + Original author: Mark Smotherman + + -------------------------------------------------------------------------*/ + + +/* tpgen.c version 1.0 + * + * generate a matrix transpose loop nest, with tiling and unrolling + * (timing code using getrusage is included in the generated program) + * + * mark smotherman + * mark@cs.clemson.edu + * clemson university + * 9 july 1993 + * + * a loop nest can be described by the order of its loop indices, so + * this program takes as input a simple language describing these indices: + * <number>d ==> generate tiling loop for index i with step size of <number> + * <number>e ==> generate tiling loop for index j with step size of <number> + * <number>i ==> generate loop for index i with unrolling factor of <number> + * <number>j ==> generate loop for index j with unrolling factor of <number> + * ; ==> input terminator (required) + * rules are: + * i,j tokens must appear + * if d appears, it must appear before i + * if e appears, it must appear before j + * ; must appear + * matrix size is controlled by #define N in this program. + * + * this code was adapted from mmgen.c v1.2 and extended to generate pre- + * condition loops for unrolling factors that do not evenly divide the + * matrix size (or the tiling step size for loop nests with a tiling loop). + * note that this program only provides a preconditioning loop for the + * innermost loop. unrolling factors for non-innermost loops that do not + * evenly divide the matrix size (or step size) are not supported. + * + * my interest in this program generator is to hook it to a sentence + * generator and a minimum execution time finder, that is + * while((sentence=sgen())!=NULL){ + * genprogram=tpgen(sentence); + * system("cc -O4 genprogram.c"); + * system("a.out >> tpresults"); + * } + * findmintime(tpresults); + * this will find the optimum algorithm for the host system via an + * exhaustive search. + * + * please report bugs and suggestions for enhancements to me. + */ + +#include <stdio.h> +#include <string.h> +#include <ctype.h> +#define N 500 + +#define ALLOC1 temp1=(struct line *)malloc(sizeof(struct line));\ +temp1->indentcnt=indentcnt; + +#define LINK1 temp1->next=insertbefore;\ +insertafter->next=temp1;\ +insertafter=temp1; + +#define INSERT1 temp1->next=start;\ +start=temp1; + +#define ALLOC2 temp1=(struct line *)malloc(sizeof(struct line));\ +temp2=(struct line *)malloc(sizeof(struct line));\ +temp1->indentcnt=indentcnt;\ +temp2->indentcnt=indentcnt++; + +#define LINK2 temp1->next=temp2;\ +temp2->next=insertbefore;\ +insertafter->next=temp1;\ +insertafter=temp1;\ +insertbefore=temp2; + +struct line{ int indentcnt; char line[256]; struct line *next; }; + +int indentcnt; +int iflag,jflag; +int ijflag,jiflag; +int dflag,eflag; +int counter; +int iistep,jjstep; +int iunroll,junroll; +int precond; + +char c; +int i,ttp,nt; +char *p0; +char tptype[80]; +char number[10]; + +struct line *start,*head,*insertafter,*insertbefore,*temp1,*temp2; + +void processloop(); +void processstmt(); + +main(){ + + indentcnt=0; + iflag=jflag=0; + ijflag=jiflag=0; + dflag=eflag=0; + iunroll=junroll=0; + counter=1; + precond=0; + ttp=0; + + start=NULL; + ALLOC2 + sprintf(temp1->line,"/* begin */\nt_start=second();\n"); + sprintf(temp2->line,"/* end */\nt_end = second();\n"); + head=temp1; temp1->next=temp2; temp2->next=NULL; + insertafter=temp1; insertbefore=temp2; + + while((c=getchar())!=';'){ + tptype[ttp++]=c; + if(isdigit(c)){ + nt=0; + while(isdigit(c)){ + number[nt++]=c; + c=getchar(); + if(c==';'){ fprintf(stderr,"unexpected ;!\n"); exit(1); } + tptype[ttp++]=c; + } + number[nt]='\0'; + sscanf(number,"%d",&counter); + } + switch(c){ + case 'd': + if(iflag){ fprintf(stderr,"d cannot appear after i!\n"); exit(1); } + dflag++; + ALLOC1 + sprintf(temp1->line,"#define IISTEP %d\n",counter); + INSERT1 + iistep=counter; + counter=1; + ALLOC2 + sprintf(temp1->line,"for(ii=0;ii<%d;ii+=IISTEP){\n",N); + sprintf(temp2->line,"}\n",N); + LINK2 + ALLOC1 + sprintf(temp1->line,"it=min(ii+IISTEP,%d);\n",N); + LINK1 + break; + case 'e': + if(jflag){ fprintf(stderr,"e cannot appear after j!\n"); exit(1); } + eflag++; + ALLOC1 + sprintf(temp1->line,"#define JJSTEP %d\n",counter); + INSERT1 + jjstep=counter; + counter=1; + ALLOC2 + sprintf(temp1->line,"for(jj=0;jj<%d;jj+=JJSTEP){\n",N); + sprintf(temp2->line,"}\n",N); + LINK2 + ALLOC1 + sprintf(temp1->line,"jt=min(jj+JJSTEP,%d);\n",N); + LINK1 + break; + case 'i': + iunroll=counter; + counter=1; + iflag++; if(jflag) jiflag++; + if(dflag) precond=iistep%iunroll; else precond=N%iunroll; + if(precond&&(jiflag==0)){ + fprintf(stderr,"unrolling factor for outer loop i\n"); + fprintf(stderr," does not evenly divide matrix/step size!\n"); + exit(1); + } + if(dflag&&(iunroll>1)&&(N%iistep)){ + fprintf(stderr,"with unrolling of i, step size for tiled loop ii\n"); + fprintf(stderr," does not evenly divide matrix size!\n"); + exit(1); + } + processloop('i',dflag,iunroll,precond,junroll); + break; + case 'j': + junroll=counter; + counter=1; + jflag++; if(iflag) ijflag++; + if(eflag) precond=jjstep%junroll; else precond=N%junroll; + if(precond&&(ijflag==0)){ + fprintf(stderr,"unrolling factor for outer loop j\n"); + fprintf(stderr," does not evenly divide matrix/step size!\n"); + exit(1); + } + if(eflag&&(junroll>1)&&(N%jjstep)){ + fprintf(stderr,"with unrolling of j, step size for tiled loop jj\n"); + fprintf(stderr," does not evenly divide matrix size!\n"); + exit(1); + } + processloop('j',eflag,junroll,precond,iunroll); + break; + default: break; + } + } + processstmt(); + + tptype[ttp++]=c; + + if((iflag==0)||(jflag==0)){ + fprintf(stderr, + "one of the loops (i,j) was not specified!\n"); + exit(1); + } + + temp1=start; + while(temp1!=NULL){ + printf("%s",temp1->line); + temp1=temp1->next; + } + printf("#include <stdio.h>\n"); + printf("#include <sys/time.h>\n"); + printf("#include <sys/resource.h>\n"); + if(dflag|eflag) printf("#define min(a,b) ((a)<=(b)?(a):(b))\n"); + printf("double second();\n"); + printf("double t_start,t_end,t_total;\n"); + printf("int times;\n"); + printf("\ndouble b[%d][%d],dummy[10000],bt[%d][%d];\n\nmain(){\n" + ,N,N,N,N); + if(precond) printf(" int i,j,n;\n"); else printf(" int i,j;\n"); + if(dflag) printf(" int ii,it;\n"); + if(eflag) printf(" int jj,jt;\n"); + printf("/* set coefficients so that result matrix should have \n"); + printf(" * column entries equal to column index\n"); + printf(" */\n"); + printf(" for (i=0;i<%d;i++){\n",N); + printf(" for (j=0;j<%d;j++){\n",N); + printf(" b[i][j] = (double) i;\n"); + printf(" }\n"); + printf(" }\n"); + printf("\n t_total=0.0;\n for(times=0;times<10;times++){\n\n",N); + printf("/* try to flush cache */\n"); + printf(" for(i=0;i<10000;i++){\n",N); + printf(" dummy[i] = 0.0;\n"); + printf(" }\n"); + printf("%s",head->line); + temp1=head->next; + while(temp1!=NULL){ + for(i=0;i<temp1->indentcnt;i++) printf(" "); + while((p0=strstr(temp1->line,"+0"))!=NULL){ + *p0++=' '; *p0=' '; + } + printf("%s",temp1->line); + temp1=temp1->next; + } + printf("\n t_total+=t_end-t_start;\n }\n"); + printf("/* check result */\n"); + printf(" for (j=0;j<%d;j++){\n",N); + printf(" for (i=0;i<%d;i++){\n",N); + printf(" if (bt[i][j]!=((double)j)){\n"); + printf(" fprintf(stderr,\"error in bt[%cd][%cd]",'%','%'); + printf("\\n\",i,j);\n"); + printf(" fprintf(stderr,\" for %s\\n\");\n",tptype); + printf(" exit(1);\n"); + printf(" }\n"); + printf(" }\n"); + printf(" }\n"); + tptype[ttp]='\0'; + printf(" printf(\"%c10.2f secs\",t_total);\n",'%'); + printf(" printf(\" for 10 runs of %s\\n\");\n",tptype); + printf("}\n"); + printf("double second(){\n"); + printf(" void getrusage();\n"); + printf(" struct rusage ru;\n"); + printf(" double t;\n"); + printf(" getrusage(RUSAGE_SELF,&ru);\n"); + printf(" t = ((double)ru.ru_utime.tv_sec) +\n"); + printf(" ((double)ru.ru_utime.tv_usec)/1.0e6;\n"); + printf(" return t;\n"); + printf("}\n"); + +} + +void processloop(index,flag,unroll,precond,unroll2) +char index; +int flag,unroll,precond,unroll2; +{ + char build[80],temp[40]; + int n; + if(precond){ + ALLOC1 + sprintf(temp1->line,"/* preconditioning loop for unrolling factor */\n"); + LINK1 + if(unroll2==1){ + build[0]='\0'; + if(flag){ + if(index='i') + sprintf(temp,"n=IISTEP%c%d; ",'%',unroll); + else + sprintf(temp,"n=JJSTEP%c%d; ",'%',unroll); + strcat(build,temp); + sprintf(temp,"for(%c=%c%c;%c<%c%c+n;%c++) ",index,index,index, + index,index,index,index); + strcat(build,temp); + }else{ + sprintf(temp,"n=%d%c%d; ",N,'%',unroll); + strcat(build,temp); + sprintf(temp,"for(%c=0;%c<n;%c++) ",index,index,index); + strcat(build,temp); + } + sprintf(temp,"bt[i][j]=b[j][i];\n"); + strcat(build,temp); + ALLOC1 + sprintf(temp1->line,"%s\n",build); + LINK1 + }else{ + if(flag){ + ALLOC1 + if(index=='i') + sprintf(temp1->line,"n=IISTEP%c%d;\n",'%',unroll); + else + sprintf(temp1->line,"n=JJSTEP%c%d;\n",'%',unroll); + LINK1 + ALLOC1 + sprintf(temp1->line,"for(%c=%c%c;%c<%c%c+n;%c++){\n",index,index,index, + index,index,index,index); + LINK1 + }else{ + ALLOC1 + sprintf(temp1->line,"n=%d%c%d;\n",N,'%',unroll); + LINK1 + ALLOC1 + sprintf(temp1->line,"for(%c=0;%c<n;%c++){\n",index,index,index); + LINK1 + } + if(index=='i'){ + for(n=0;n<unroll2;n++){ + ALLOC1 + sprintf(temp1->line," bt[i][j+%d]=b[j+%d][i];\n",n,n); + LINK1 + } + }else{ + for(n=0;n<unroll2;n++){ + ALLOC1 + sprintf(temp1->line," bt[i+%d][j]=b[j][i+%d];\n",n,n); + LINK1 + } + } + ALLOC1 + sprintf(temp1->line,"}\n"); + LINK1 + } + ALLOC2 + if(flag){ + sprintf(temp1->line,"for(%c=%c%c+n;%c<%ct;%c+=%d){\n",index,index,index, + index,index,index,unroll); + }else{ + sprintf(temp1->line,"for(%c=n;%c<%d;%c+=%d){\n",index,index,N,index, + unroll); + } + sprintf(temp2->line,"}\n",N); + LINK2 + }else{ + ALLOC2 + if(unroll==1){ + if(flag){ + sprintf(temp1->line,"for(%c=%c%c;%c<%ct;%c++){\n",index,index,index, + index,index,index); + }else{ + sprintf(temp1->line,"for(%c=0;%c<%d;%c++){\n",index,index,N,index); + } + }else{ + if(flag){ + sprintf(temp1->line,"for(%c=%c%c;%c<%ct;%c+=%d){\n",index,index,index, + index,index,index,unroll); + }else{ + sprintf(temp1->line,"for(%c=0;%c<%d;%c+=%d){\n",index,index,N,index, + unroll); + } + } + sprintf(temp2->line,"}\n",N); + LINK2 + } +} + +void processstmt() +{ + int i,j; + for(i=0;i<iunroll;i++){ + for(j=0;j<junroll;j++){ + ALLOC1 + sprintf(temp1->line,"bt[i+%d][j+%d]=b[j+%d][i+%d];\n",i,j,j,i); + LINK1 + } + } +} +-- +Mark Smotherman, Computer Science Dept., Clemson University, Clemson, SC + +======================================================================= +From: has (h.genceli@bre.com) + Subject: transpose of a nxm matrix stored in a vector !!! + Newsgroups: sci.math.num-analysis + Date: 2000/07/25 + + +If I have a matrix nrows x ncols, I can store it in a vector. +so A(i,j) is really a[i*ncols+j]. So really TRANS of A +(say B) is really is also a vector B where + +0<=i b[j*nrows+i] <nrows, 0<=j<ncols +b[j*nrows+i] = a[i*ncols+j]. + +Fine but I want to use only one array a to do this transformation. + +i.e a[j*nrows+i] = a[i*ncols+j]. this will itself +erase some elements so each time a swap is necessary in a loop. + +temp = a[j*nrows+i] +a[j*nrows+i] = a[i*ncols+j] +a[i*ncols+j] = temp + +but still this will lose some info as it is, so indexing +should have more intelligence in it ???? anybody +can give me a lead here, thanks. + +Has + + From: wei-choon ng (wng@ux8.cso.uiuc.edu) + Subject: Re: transpose of a nxm matrix stored in a vector !!! + Newsgroups: sci.math.num-analysis + Date: 2000/07/25 + + +has <h.genceli@bre.com> wrote: +> If I have a matrix nrows x ncols, I can store it in a vector. +> so A(i,j) is really a[i*ncols+j]. So really TRANS of A +> (say B) is really is also a vector B where + +[snip] + +Hey, if you just want to do a transpose-matrix vector multiply, there is +no need to explicitly store the transpose matrix in another array and +doubling the storage! + +W.C. +-- + + From: Robin Becker (robin@jessikat.fsnet.co.uk) + Subject: Re: transpose of a nxm matrix stored in a vector !!! + Newsgroups: sci.math.num-analysis + Date: 2000/07/25 + + +In article <snr532fo3j1180@corp.supernews.com>, has <h.genceli@bre.com> +writes +>If I have a matrix nrows x ncols, I can store it in a vector. +>so A(i,j) is really a[i*ncols+j]. So really TRANS of A +>(say B) is really is also a vector B where +> +>0<=i b[j*nrows+i] <nrows, 0<=j<ncols +>b[j*nrows+i] = a[i*ncols+j]. +> +>Fine but I want to use only one array a to do this transformation. +> +>i.e a[j*nrows+i] = a[i*ncols+j]. this will itself +>erase some elements so each time a swap is necessary in a loop. +> +>temp = a[j*nrows+i] +>a[j*nrows+i] = a[i*ncols+j] +>a[i*ncols+j] = temp +> +>but still this will lose some info as it is, so indexing +>should have more intelligence in it ???? anybody +>can give me a lead here, thanks. +> +>Has +> +> +> + +void dmx_transpose(unsigned n, unsigned m, double* a, double* b) +{ + unsigned size = m*n; + if(b!=a){ + real *bmn, *aij, *anm; + bmn = b + size; /*b+n*m*/ + anm = a + size; + while(b<bmn) for(aij=a++;aij<anm; aij+=n ) *b++ = *aij; + } + else if(size>3){ + unsigned i,row,column,current; + for(i=1, size -= 2;i<size;i++){ + current = i; + do { + /*current = row+n*column*/ + column = current/m; + row = current%m; + current = n*row + column; + } while(current < i); + + if (current >i) { + real temp = a[i]; + a[i] = a[current]; + a[current] = temp; + } + } + } +} +-- +Robin Becker + + From: E. Robert Tisdale (edwin@netwood.net) + Subject: Re: transpose of a nxm matrix stored in a vector !!! + Newsgroups: sci.math.num-analysis + Date: 2000/07/25 + + +Take a look at +The C++ Scalar, Vector, Matrix and Tensor class library + + http://www.netwood.net/~edwin/svmt/ + +<Type><System>SubVector& + <Type><System>SubVector::transpose(Extent p, Extent q) { + <Type><System>SubVector& + v = *this; + if (1 < p && 1 < q) { + // A vector v of extent n = qp is viewed as a q by p matrix U and + // a p by q matrix V where U_{ij} = v_{p*i+j} and V_{ij} = v_{q*i+j}. + // The vector v is modified in-place so that V is the transpose of U. + // The algorithm searches for every sequence k_s of S indices + // such that a circular shift of elements v_{k_s} <-- v_{k_{s+1}} + // and v_{k_{S-1}} <-- v_{k_0} effects an in-place transpose. + Extent n = q*p; + Extent m = 0; // count up to n-2 + Offset l = 0; // 1 <= l <= n-2 + while (++l < n-1 && m < n-2) { + Offset k = l; + Offset j = k; + while (l < (k = (j%p)*q + j/p)) { // Search backward for k < l. + j = k; + } + // If a sequence of indices beginning with l has any index k < l, + // it has already been transposed. The sequence length S = 1 + // and diagonal element v_k is its own transpose if k = j. + // Skip every index sequence that has already been transposed. + if (k == l) { // a new sequence + if (k < j) { // with 1 < S + TYPE x = v[k]; // save v_{k_0} + do { + v[k] = v[j]; // v_{k_{s}} <-- v_{k_{s+1}} + k = j; + ++m; + } while (l < (j = (k%q)*p + k/q)); + v[k] = x; // v_{k_{S-1}} <-- v_{k_0} + } + ++m; + } + } + } return v; + } + + + +<Type><System>SubVector& + +Read the rest of this message... (50 more lines) + + From: Victor Eijkhout (eijkhout@disco.cs.utk.edu) + Subject: Re: transpose of a nxm matrix stored in a vector !!! + Newsgroups: sci.math.num-analysis + Date: 2000/07/25 + + +"Alan Miller" <amiller @ vic.bigpond.net.au> writes: + +> The attached routine does an in situ transpose. +> begin 666 Dtip.f90 +> M4U5"4D]55$E.12!D=&EP("AA+"!N,2P@;C(L(&YD:6TI#0HA("TM+2TM+2TM + +Hm. F90? You're not silently allocating a temporary I hope? + +(Why did you have to encode this? Now I have to save, this decode, ... +and all for plain ascii?) + +-- +Victor Eijkhout +"When I was coming up, [..] we knew exactly who the they were. It was us +versus them, and it was clear who the them was were. Today, we are not +so sure who the they are, but we know they're there." [G.W. Bush] + + From: Alan Miller (amiller_@_vic.bigpond.net.au) + Subject: Re: transpose of a nxm matrix stored in a vector !!! + Newsgroups: sci.math.num-analysis + Date: 2000/07/25 + + +Victor Eijkhout wrote in message ... +>"Alan Miller" <amiller @ vic.bigpond.net.au> writes: +> +>> The attached routine does an in situ transpose. +>> begin 666 Dtip.f90 +>> M4U5"4D]55$E.12!D=&EP("AA+"!N,2P@;C(L(&YD:6TI#0HA("TM+2TM+2TM +> +>Hm. F90? You're not silently allocating a temporary I hope? +> +>(Why did you have to encode this? Now I have to save, this decode, ... +>and all for plain ascii?) +> + +I know the problem. +I sometimes use a Unix system, and have to use decode64 to read +attachments. On the other hand, Windows wraps lines around, +formats then and generally makes the code unreadable. + +The straight code for dtip (double transpose in place) is attached +this time. + +>-- +>Victor Eijkhout + + +-- +Alan Miller, Retired Scientist (Statistician) +CSIRO Mathematical & Information Sciences +Alan.Miller -at- vic.cmis.csiro.au +http://www.ozemail.com.au/~milleraj +http://users.bigpond.net.au/amiller/ + + +================================================================= + +From: Darran Edmundson (dedmunds@sfu.ca) + Subject: array reordering algorithm? + Newsgroups: sci.math.num-analysis + Date: 1995/04/30 + + +A code I've written refers to a complex array as two separate real arrays. +However, I have a canned subroutine which expects a single array where the +real and imaginary values alternate. Essentially I have a case of mismatched +data structures, yet for reasons that I'd rather not go into, I'm stuck with them. + +Assuming that the two real arrays A and B are sequential in memory, and +that the single array of alternating real/imaginary values C shares the same +space, what I need is a porting subroutine that remaps the data from one format +to the other - using as little space as possible. + +I think of the problem as follows. Imagine an array of dimension 10 containing +the values 1,3,5,7,9,2,4,6,8,10 in this order. + + A(1) / 1 \ C(1) + A(2) | 3 | C(2) + A(3) | 5 | C(3) + A(4) | 7 | C(4) + A(5) \ 9 | C(5) + | + B(1) / 2 | C(6) + B(2) | 4 | C(7) + B(3) | 6 | C(8) + B(4) | 8 | C(9) + B(5) \ 10 / C(10) + +Given that I know this initial pattern, I want to sort the array C in-place *without +making comparisons*. That is, the algorithm can only depend on the initial +knowledge of the pattern. Do you see what a sort is going to do? It will +make the A and B arrays alternate, i.e. C(1)=A(1), C(2)=B(1), C(3)=A(2), +C(4)=B(2), etc. It's not a real sort though because I can't actually refer to the +values above (i.e. no comparisons) because A and B will be holding real data, +not this contrived pattern. The pattern above exists though - it's the +natural ordering in memory of A and B. + +Either pair swapping only or a small amount of workspace can be used. The +in-place is important - imagine scaling this problem up to an +array of 32 or 64 million double precision values and you can easily see how +duplicating the array is not a feasible solution. + +Any ideas? I've been stumped on this for a day and a half now. + +Darran Edmundson +dedmunds@sfu.ca + + From: Roger Critchlow (rec@elf115.elf.org) + Subject: Re: array reordering algorithm? + Newsgroups: sci.math.num-analysis + Date: 1995/04/30 + + + Any ideas? I've been stumped on this for a day and a half now. + +Here's some code for in situ permutations of arrays that I wrote +a few years ago. It all started from the in situ transposition +algorithms in the Collected Algorithms of the ACM, the references +for which always get lost during the decryption from fortran. + +This is the minimum space algorithm. All you need to supply is +a function which computes the new order array index from the old +order array index. + +If you can spare n*m bits to record the indexes of elements which +have been permuted, then you can speed things up. + +-- rec -- + +------------------------------------------------------------------------ +/* +** Arbitrary in situ permutations of an m by n array of base type TYPE. +** Copyright 1995 by Roger E Critchlow Jr, rec@elf.org, San Francisco, CA. +** Fair use permitted, caveat emptor. +*/ +typedef int TYPE; + +int transposition(int ij, int m, int n) /* transposition about diagonal from upper left to lower right */ +{ return ((ij%m)*n+ (ij/m)); } + +int countertrans(int ij, int m, int n) /* transposition about diagonal from upper right to lower left */ +{ return ((m-1-(ij%m))*n+ (n-1-(ij/m))); } + +int rotate90cw(int ij, int m, int n) /* 90 degree clockwise rotation */ +{ return ((m-1-(ij%m))*n+ (ij/m)); } + +int rotate90ccw(int ij, int m, int n) /* 90 degree counter clockwise rotation */ +{ return ((ij%m)*n+ (n-1-(ij/m))); } + +int rotate180(int ij, int m, int n) /* 180 degree rotation */ +{ return ((m-1-(ij/n))*n+ (n-1-(ij%n))); } + +int reflecth(int ij, int m, int n) /* reflection across horizontal plane */ +{ return ((m-1-(ij/n))*n+ (ij%n)); } + +int reflectv(int ij, int m, int n) /* reflection across vertical plane */ +{ return ((ij/n)*n+ (n-1-(ij%n))); } + +int in_situ_permutation(TYPE a[], int m, int n, int (*origination)(int ij, int m, int n)) +{ + int ij, oij, dij, n_to_do; + TYPE b; + n_to_do = m*n; + for (ij = 0; ij < m*n && n_to_do > 0; ij += 1) { + /* Test for previously permuted */ + for (oij = origination(ij,m,n); oij > ij; oij = origination(oij,m,n)) + ; + if (oij < ij) + continue; + /* Chase the cycle */ + dij = ij; + b = a[ij]; + for (oij = origination(dij,m,n); oij != ij; oij = origination(dij,m,n)) { + a[dij] = a[oij]; + dij = oij; + n_to_do -= 1; + } + a[dij] = b; + n_to_do -= 1; + } return 0; +} + +#define TESTING 1 +#if TESTING + +/* fill a matrix with sequential numbers, row major ordering */ +void fill_matrix_rows(a, m, n) TYPE *a; int m, n; +{ + int i, j; + for (i = 0; i < m; i += 1) + for (j = 0; j < n; j += 1) + a[i*n+j] = i*n+j; +} + +/* fill a matrix with sequential numbers, column major ordering */ +void fill_matrix_cols(a, m, n) TYPE *a; int m, n; +{ + int i, j; + for (i = 0; i < m; i += 1) + for (j = 0; j < n; j += 1) + a[i*n+j] = j*m+i; +} + +/* test a matrix for sequential numbers, row major ordering */ +int test_matrix_rows(a, m, n) TYPE *a; int m, n; +{ + int i, j, o; + for (o = i = 0; i < m; i += 1) + for (j = 0; j < n; j += 1) + o += a[i*n+j] != i*n+j; + return o; +} + +/* test a matrix for sequential numbers, column major ordering */ +int test_matrix_cols(a, m, n) TYPE *a; int m, n; +{ + int i, j, o; + for (o = i = 0; i < m; i += 1) + for (j = 0; j < n; j += 1) + o += a[i*n+j] != j*m+i; + return o; +} + +/* print a matrix */ +void print_matrix(a, m, n) TYPE *a; int m, n; +{ + char *format; + int i, j; + if (m*n < 10) format = "%2d"; + if (m*n < 100) format = "%3d"; + if (m*n < 1000) format = "%4d"; + if (m*n < 10000) format = "%5d"; + for (i = 0; i < m; i += 1) { + for (j = 0; j < n; j += 1) + printf(format, a[i*n+j]); + printf("\n"); + } +} + +#if TEST_TRANSPOSE +#define MAXSIZE 1000 + +main() +{ + int i, j, m, n, o; + TYPE a[MAXSIZE]; + for (m = 1; m < sizeof(a)/sizeof(a[0]); m += 1) + for (n = 1; m*n < sizeof(a)/sizeof(a[0]); n += 1) { + fill_matrix_rows(a, m, n); /* {0 1} {2 3} */ + if (o = transpose(a, m, n)) + printf(">> transpose returned %d for a[%d][%d], row major\n", o, m, n); + if ((o = test_matrix_cols(a, n, m)) != 0) /* {0 2} {1 3} */ + printf(">> transpose made %d mistakes for a[%d][%d], row major\n", o, m, n); + /* column major */ + fill_matrix_rows(a, m, n); + if (o = transpose(a, m, n)) + printf(">> transpose returned %d for a[%d][%d], column major\n", o, m, n); + if ((o = test_matrix_cols(a, n, m)) != 0) + printf(">> transpose made %d mistakes for a[%d][%d], column major\n", o, m, n); + } return 0; +} +#endif /* TEST_TRANSPOSE */ + + +#define TEST_DISPLAY 1 +#if TEST_DISPLAY +main(argc, argv) int argc; char *argv[]; +{ + TYPE *a; + int m = 5, n = 5; + extern void *malloc(); + if (argc > 1) { + m = atoi(argv[1]); + if (argc > 2) + n = atoi(argv[2]); + } + a = malloc(m*n*sizeof(TYPE)); + + printf("matrix\n"); + fill_matrix_rows(a, m, n); + print_matrix(a, m, n); + printf("transposition\n"); + in_situ_permutation(a, m, n, transposition); + print_matrix(a, n, m); + + printf("counter transposition\n"); + fill_matrix_rows(a, m, n); + in_situ_permutation(a, m, n, countertrans); + print_matrix(a, n, m); + + printf("rotate 90 degrees clockwise\n"); + fill_matrix_rows(a, m, n); + in_situ_permutation(a, m, n, rotate90cw); + print_matrix(a, n, m); + + printf("rotate 90 degrees counterclockwise\n"); + fill_matrix_rows(a, m, n); + in_situ_permutation(a, m, n, rotate90ccw); + print_matrix(a, n, m); + + printf("rotate 180 degrees\n"); + fill_matrix_rows(a, m, n); + in_situ_permutation(a, m, n, rotate180); + print_matrix(a, m, n); + + printf("reflect across horizontal\n"); + fill_matrix_rows(a, m, n); + in_situ_permutation(a, m, n, reflecth); + print_matrix(a, m, n); + + printf("reflect across vertical\n"); + fill_matrix_rows(a, m, n); + in_situ_permutation(a, m, n, reflectv); + print_matrix(a, m, n); + + return 0; +} + +#endif +#endif + diff --git a/numpy/f2py/doc/multiarrays.txt b/numpy/f2py/doc/multiarrays.txt new file mode 100644 index 000000000..704208976 --- /dev/null +++ b/numpy/f2py/doc/multiarrays.txt @@ -0,0 +1,120 @@ +From pearu@ioc.ee Thu Dec 30 09:58:01 1999 +Date: Fri, 26 Nov 1999 12:02:42 +0200 (EET) +From: Pearu Peterson <pearu@ioc.ee> +To: Users of f2py2e -- Curtis Jensen <cjensen@be-research.ucsd.edu>, + Vladimir Janku <vjanku@kvet.sk>, + Travis Oliphant <Oliphant.Travis@mayo.edu> +Subject: Multidimensional arrays in f2py2e + + +Hi! + +Below I will describe how f2py2e wraps Fortran multidimensional arrays as +it constantly causes confusion. As for example, consider Fortran code + + subroutine foo(l,m,n,a) + integer l,m,n + real*8 a(l,m,n) + .. + end +Running f2py2e with -h flag, it generates the following signature + +subroutine foo(l,m,n,a) + integer optional,check(shape(a,2)==l),depend(a) :: l=shape(a,2) + integer optional,check(shape(a,1)==m),depend(a) :: m=shape(a,1) + integer optional,check(shape(a,0)==n),depend(a) :: n=shape(a,0) + real*8 dimension(l,m,n),check(rank(a)==3) :: a +end subroutine foo + +where parameters l,m,n are considered optional and they are initialized in +Python C/API code using the array a. Note that a can be also a proper +list, that is, asarray(a) should result in a rank-3 array. But then there +is an automatic restriction that elements of a (in Python) are not +changeable (in place) even if Fortran subroutine changes the array a (in +C,Fortran). + +Hint: you can attribute the array a with 'intent(out)' which causes foo to +return the array a (in Python) if you are to lazy to define a=asarray(a) +before the call to foo (in Python). + +Calling f2py2e without the switch -h, a Python C/API module will be +generated. After compiling it and importing it to Python +>>> print foo.__doc__ +shows +None = foo(a,l=shape(a,2),m=shape(a,1),n=shape(a,0)) + +You will notice that f2py2e has changed the order of arguments putting the +optional ones at the end of the argument list. +Now, you have to be careful when specifying the parameters l,m,n (though +situations where you need this should be rare). A proper definition +of the array a should be, say + + a = zeros(n,m,l) + +Note that the dimensions l,m,n are in reverse, that is, the array a should +be transposed when feeding it to the wrapper. + +Hint (and a performance hit): To be always consistent with fortran +arrays, you can define, for example + a = zeros(l,m,n) +and call from Python + foo(transpose(a),l,m,n) +which is equivalent with the given Fortran call + call foo(l,m,n,a) + +Another hint (not recommended, though): If you don't like optional +arguments feature at all and want to be strictly consistent with Fortran +signature, that is, you want to call foo from Python as + foo(l,m,n,a) +then you should edit the signature to +subroutine foo(l,m,n,a) + integer :: l + integer :: m + integer :: n + real*8 dimension(l,m,n),check(rank(a)==3),depend(l,m,n), & + check(shape(a,2)==l,shape(a,1)==m,shape(a,0)==n):: a +end +Important! Note that now the array a should depend on l,m,n +so that the checks can be performed in the proper order. +(you cannot check, say, shape(a,2)==l before initializing a or l) +(There are other ways to edit the signature in order to get the same +effect but they are not so safe and I will not discuss about them here). + +Hint: If the array a should be a work array (as used frequently in +Fortran) and you a too lazy (its good lazyness;) to provide it (in Python) +then you can define it as optional by ediding the signature: +subroutine foo(l,m,n,a) + integer :: l + integer :: m + integer :: n + real*8 dimension(l,m,n),check(rank(a)==3),depend(l,m,n), & + check(shape(a,2)==l,shape(a,1)==m,shape(a,0)==n):: a + optional a +end +Note again that the array a must depend on l,m,n. Then the array a will be +allocated in the Python C/API module. Not also that +>>> print foo.__doc__ +shows then +None = foo(l,m,n,a=) +Performance hint: If you call the given foo lots of times from Python then +you don't want to allocate/deallocate the memory in each call. So, it is +then recommended to define a temporary array in Python, for instance +>>> tmp = zeros(n,m,l) +>>> for i in ...: +>>> foo(l,m,n,a=tmp) + +Important! It is not good at all to define + >>> tmp = transpose(zeros(l,m,n)) +because tmp will be then a noncontiguous array and there will be a +huge performance hit as in Python C/API a new array will be allocated and +also a copying of arrays will be performed elementwise! +But + >>> tmp = asarray(transpose(zeros(l,m,n))) +is still ok. + +I hope that the above answers lots of your (possible) questions about +wrapping Fortran multidimensional arrays with f2py2e. + +Regards, + Pearu + diff --git a/numpy/f2py/doc/notes.tex b/numpy/f2py/doc/notes.tex new file mode 100644 index 000000000..2746b049d --- /dev/null +++ b/numpy/f2py/doc/notes.tex @@ -0,0 +1,310 @@ + +\section{Calling wrapper functions from Python} +\label{sec:notes} + +\subsection{Scalar arguments} +\label{sec:scalars} + +In general, for scalar argument you can pass in in +addition to ordinary Python scalars (like integers, floats, complex +values) also arbitrary sequence objects (lists, arrays, strings) --- +then the first element of a sequence is passed in to the Fortran routine. + +It is recommended that you always pass in scalars of required type. This +ensures the correctness as no type-casting is needed. +However, no exception is raised if type-casting would produce +inaccurate or incorrect results! For example, in place of an expected +complex value you can give an integer, or vice-versa (in the latter case only +a rounded real part of the complex value will be used). + +If the argument is \texttt{intent(inout)} then Fortran routine can change the +value ``in place'' only if you pass in a sequence object, for +instance, rank-0 array. Also make sure that the type of an array is of +correct type. Otherwise type-casting will be performed and you may +get inaccurate or incorrect results. The following example illustrates this +\begin{verbatim} +>>> a = array(0) +>>> calculate_pi(a) +>>> print a +3 +\end{verbatim} + +If you pass in an ordinary Python scalar in place of +\texttt{intent(inout)} variable, it will be used as an input argument +since +Python +scalars cannot not be changed ``in place'' (all Python scalars +are immutable objects). + +\subsection{String arguments} +\label{sec:strings} + +You can pass in strings of arbitrary length. If the length is greater than +required, only a required part of the string is used. If the length +is smaller than required, additional memory is allocated and fulfilled +with `\texttt{\bs0}'s. + +Because Python strings are immutable, \texttt{intent(inout)} argument +expects an array version of a string --- an array of chars: +\texttt{array("<string>")}. +Otherwise, the change ``in place'' has no effect. + + +\subsection{Array arguments} +\label{sec:arrays} + +If the size of an array is relatively large, it is \emph{highly + recommended} that you pass in arrays of required type. Otherwise, +type-casting will be performed which includes the creation of new +arrays and their copying. If the argument is also +\texttt{intent(inout)}, the wasted time is doubled. So, pass in arrays +of required type! + +On the other hand, there are situations where it is perfectly all +right to ignore this recommendation: if the size of an array is +relatively small or the actual time spent in Fortran routine takes +much longer than copying an array. Anyway, if you want to optimize +your Python code, start using arrays of required types. + +Another source of performance hit is when you use non-contiguous +arrays. The performance hit will be exactly the same as when using +incorrect array types. This is because a contiguous copy is created +to be passed in to the Fortran routine. + +\fpy provides a feature such that the ranks of array arguments need +not to match --- only the correct total size matters. For example, if +the wrapper function expects a rank-1 array \texttt{array([...])}, +then it is correct to pass in rank-2 (or higher) arrays +\texttt{array([[...],...,[...]])} assuming that the sizes will match. +This is especially useful when the arrays should contain only one +element (size is 1). Then you can pass in arrays \texttt{array(0)}, +\texttt{array([0])}, \texttt{array([[0]])}, etc and all cases are +handled correctly. In this case it is correct to pass in a Python +scalar in place of an array (but then ``change in place'' is ignored, +of course). + +\subsubsection{Multidimensional arrays} + +If you are using rank-2 or higher rank arrays, you must always +remember that indexing in Fortran starts from the lowest dimension +while in Python (and in C) the indexing starts from the highest +dimension (though some compilers have switches to change this). As a +result, if you pass in a 2-dimensional array then the Fortran routine +sees it as the transposed version of the array (in multi-dimensional +case the indexes are reversed). + +You must take this matter into account also when modifying the +signature file and interpreting the generated Python signatures: + +\begin{itemize} +\item First, when initializing an array using \texttt{init\_expr}, the index +vector \texttt{\_i[]} changes accordingly to Fortran convention. +\item Second, the result of CPP-macro \texttt{shape(<array>,0)} + corresponds to the last dimension of the Fortran array, etc. +\end{itemize} +Let me illustrate this with the following example:\\ +\begin{verbatim} +! Fortran file: arr.f + subroutine arr(l,m,n,a) + integer l,m,n + real*8 a(l,m,n) + ... + end +\end{verbatim} +\fpy will generate the following signature file:\\ +\begin{verbatim} +!%f90 +! Signature file: arr.f90 +python module arr ! in + interface ! in :arr + subroutine arr(l,m,n,a) ! in :arr:arr.f + integer optional,check(shape(a,2)==l),depend(a) :: l=shape(a,2) + integer optional,check(shape(a,1)==m),depend(a) :: m=shape(a,1) + integer optional,check(shape(a,0)==n),depend(a) :: n=shape(a,0) + real*8 dimension(l,m,n) :: a + end subroutine arr + end interface +end python module arr +\end{verbatim} +and the following wrapper function will be produced +\begin{verbatim} +None = arr(a,l=shape(a,2),m=shape(a,1),n=shape(a,0)) +\end{verbatim} + +In general, I would suggest not to specify the given optional +variables \texttt{l,m,n} when calling the wrapper function --- let the +interface find the values of the variables \texttt{l,m,n}. But there +are occasions when you need to specify the dimensions in Python. + +So, in Python a proper way to create an array from the given +dimensions is +\begin{verbatim} +>>> a = zeros(n,m,l,'d') +\end{verbatim} +(note that the dimensions are reversed and correct type is specified), +and then a complete call to \texttt{arr} is +\begin{verbatim} +>>> arr(a,l,m,n) +\end{verbatim} + +From the performance point of view, always be consistent with Fortran +indexing convention, that is, use transposed arrays. But if you do the +following +\begin{verbatim} +>>> a = transpose(zeros(l,m,n,'d')) +>>> arr(a) +\end{verbatim} +then you will get a performance hit! The reason is that here the +transposition is not actually performed. Instead, the array \texttt{a} +will be non-contiguous which means that before calling a Fortran +routine, internally a contiguous array is created which +includes memory allocation and copying. In addition, if +the argument array is also \texttt{intent(inout)}, the results are +copied back to the initial array which doubles the +performance hit! + +So, to improve the performance: always pass in +arrays that are contiguous. + +\subsubsection{Work arrays} + +Often Fortran routines use the so-called work arrays. The +corresponding arguments can be declared as optional arguments, but be +sure that all dimensions are specified (bounded) and defined before +the initialization (dependence relations). + +On the other hand, if you call the Fortran routine many times then you +don't want to allocate/deallocate the memory of the work arrays on +every call. In this case it is recommended that you create temporary +arrays with proper sizes in Python and use them as work arrays. But be +careful when specifying the required type and be sure that the +temporary arrays are contiguous. Otherwise the performance hit would +be even harder than the hit when not using the temporary arrays from +Python! + + + +\subsection{Call-back arguments} +\label{sec:cbargs} + +\fpy builds a very flexible call-back mechanisms for call-back +arguments. If the wrapper function expects a call-back function \texttt{fun} +with the following Python signature to be passed in +\begin{verbatim} +def fun(a_1,...,a_n): + ... + return x_1,...,x_k +\end{verbatim} +but the user passes in a function \texttt{gun} with the signature +\begin{verbatim} +def gun(b_1,...,b_m): + ... + return y_1,...,y_l +\end{verbatim} +and the following extra arguments (specified as additional optional +argument for the wrapper function): +\begin{verbatim} +fun_extra_args = (e_1,...,e_p) +\end{verbatim} +then the actual call-back is constructed accordingly to the following rules: +\begin{itemize} +\item if \texttt{p==0} then \texttt{gun(a\_1,...,a\_q)}, where + \texttt{q=min(m,n)}; +\item if \texttt{n+p<=m} then \texttt{gun(a\_1,...,a\_n,e\_1,...,e\_p)}; +\item if \texttt{p<=m<n+p} then \texttt{gun(a\_1,...,a\_q,e\_1,...,e\_p)}, + where \texttt{q=m-p}; +\item if \texttt{p>m} then \texttt{gun(e\_1,...,e\_m)}; +\item if \texttt{n+p} is less than the number of required arguments + of the function \texttt{gun}, an exception is raised. +\end{itemize} + +A call-back function \texttt{gun} may return any number of objects as a tuple: +if \texttt{k<l}, then objects \texttt{y\_k+1,...,y\_l} are ignored; +if \texttt{k>l}, then only objects \texttt{x\_1,...,x\_l} are set. + + +\subsection{Obtaining information on wrapper functions} +\label{sec:info} + +From the previous sections we learned that it is useful for the +performance to pass in arguments of expected type, if possible. To +know what are the expected types, \fpy generates a complete +documentation strings for all wrapper functions. You can read them +from Python by printing out \texttt{\_\_doc\_\_} attributes of the +wrapper functions. For the example in Sec.~\ref{sec:intro}: +\begin{verbatim} +>>> print foobar.foo.__doc__ +Function signature: + foo(a) +Required arguments: + a : in/output rank-0 array(int,'i') +>>> print foobar.bar.__doc__ +Function signature: + bar = bar(a,b) +Required arguments: + a : input int + b : input int +Return objects: + bar : int +\end{verbatim} + +In addition, \fpy generates a LaTeX document +(\texttt{<modulename>module.tex}) containing a bit more information on +the wrapper functions. See for example Appendix that contains a result +of the documentation generation for the example module +\texttt{foobar}. Here the file \texttt{foobar-smart.f90} (modified +version of \texttt{foobar.f90}) is used --- it contains +\texttt{note(<LaTeX text>)} attributes for specifying some additional +information. + +\subsection{Wrappers for common blocks} +\label{sec:wrapcomblock} + +[See examples \texttt{test-site/e/runme*}] + +What follows is obsolute for \fpy version higher that 2.264. + +\fpy generates wrapper functions for common blocks. For every common +block with a name \texttt{<commonname>} a function +\texttt{get\_<commonname>()} is constructed that takes no arguments +and returns a dictionary. The dictionary represents maps between the +names of common block fields and the arrays containing the common +block fields (multi-dimensional arrays are transposed). So, in order +to access to the common block fields, you must first obtain the +references +\begin{verbatim} +commonblock = get_<commonname>() +\end{verbatim} +and then the fields are available through the arrays +\texttt{commonblock["<fieldname>"]}. +To change the values of common block fields, you can use for scalars +\begin{verbatim} +commonblock["<fieldname>"][0] = <new value> +\end{verbatim} +and for arrays +\begin{verbatim} +commonblock["<fieldname>"][:] = <new array> +\end{verbatim} +for example. + +For more information on the particular common block wrapping, see +\texttt{get\_<commonname>.\_\_doc\_\_}. + +\subsection{Wrappers for F90/95 module data and routines} +\label{sec:wrapf90modules} + +[See example \texttt{test-site/mod/runme\_mod}] + +\subsection{Examples} +\label{sec:examples} + +Examples on various aspects of wrapping Fortran routines to Python can +be found in directories \texttt{test-site/d/} and +\texttt{test-site/e/}: study the shell scripts \texttt{runme\_*}. See +also files in \texttt{doc/ex1/}. + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "f2py2e" +%%% End: diff --git a/numpy/f2py/doc/oldnews.html b/numpy/f2py/doc/oldnews.html new file mode 100644 index 000000000..0e09c032f --- /dev/null +++ b/numpy/f2py/doc/oldnews.html @@ -0,0 +1,121 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> +<HTML> +<HEAD> +<META name="Author" content="Pearu Peterson"> +<!-- You may add here some keywords (comma separeted list) --> +<META name="Keywords" content="fortran,python,interface,f2py,f2py2e,wrapper,fpig"> +<TITLE>F2PY - Fortran to Python Interface Generator</TITLE> +<LINK rel="stylesheet" type="text/css" href="/styles/userstyle.css"> +</HEAD> + +<body> +<h2><a href="http://cens.ioc.ee/projects/f2py2e">F2PY</a> old news.</h2> + +<dl> + <dt> February 23, 2002 + <dd> Fixed a bug of incorrect shapes of multi-dimensional arrays + when returning from Fortran routine (thanks to Eric for pointing + this out). + <code>F2PY_REPORT_ATEXIT</code> is disabled by default under Win32. + <dt> February 14, 2002 + <dd> Introduced <code>callprotoargument</code> statement so that + proper prototypes can be specified (this fixes SEGFAULTs when + wrapping C functions with <code>f2py</code>, see <a + href="NEWS.txt">NEWS.txt</a> for more details). Updated for the + latest <code>numpy_distutils</code>. Fixed few bugs. + <dt> February 3, 2002 + <dd> Introduced <code>intent(overwrite),intent(out=name)</code> + attributes, <code>callstatement C-expr;</code> statement, and + reviewed reference counting in callback mechanism. Fixed bugs. + <dt> January 18, 2002 + <dd> Introduced extra keyword argument <code>copy_#varname#=1</code> + for <code>intent(copy)</code> variables, + <code>-DF2PY_REPORT_ATEXIT</code> for reporting <code>f2py</code> + performance, + <code>has_column_major_storage</code> member function for generated + modules, and <a href="http://dmalloc.com/">dmalloc</a> support. + <dt> January 16, 2002 + <dd> BREAKING NEWS! Solved long lasted dilemma of wrapping + multi-dimensional arrays where different + storage orders in C and Fortran come into account. From now on + this difference is dealt automatically by the f2py generated + module and in a very efficient way. For example, the corresponding + element A(i,j) of a Fortran array can be accessed in Python as + A[i,j]. + <dt> January 13, 2002 + <dd> Fifth Public Release is coming soon..., a snapshot is available + for download, now with updates. + <dt> December 17, 2001 + <dd> <a href="Release-4.x.txt">Fourth Public Release</a>: Win32 support. + <dd> Making <code>f2py2e</code> a module. Currently it has only one + member function <code>run_main(comline_list)</code>. + <dd> Removed command line arguments <code>-fix,-f90,-f77</code> + and introduced many new ones. See <a href="NEWS.txt">NEWS.txt</a>. + <dd> <code>intent(..)</code> statement with empty name list defines + default <code>intent(..)</code> attribute for all routine arguments. + <dd> Refinements in Win32 support. Eric Jones has provided a f2py + HOWTO for Windows users. See <a href="win32_notes.txt">win32_notes.txt</a>. + <dd> Major rewrote of the code generator to achieve + a higher quality of generated C/API modules (-Wall messages are + considerably reduced, especially for callback functions). + <dd> Many bugs were fixed. + <dt> December 12, 2001 + <dd> Win32 support (thanks to Eric Jones and Tiffany Kamm). Minor + cleanups and fixes. + <dt> December 4, 2001 + <dd> <a href="Release-3.x.txt">Third Public Release</a>: <code>f2py</code> supports <code>distutils</code>. It can be + installed with one and it generates <code>setup_modulename.py</code> + to be used for building Python extension modules. + <dd> Introduced <code>threadsafe</code>, <code>fortranname</code>, + and <code>intent(c)</code> statements. + <dt> August 13, 2001 + <dd> Changed the name FPIG to F2PY for avoiding confusion with project names. + <dd> Updated <code>f2py</code> for use with Numeric version 20.x. + <dt> January 12, 2001 + <dd> Example usages of <a href="pyfobj.html"><code>PyFortranObject</code></a>. + Fixed bugs. Updated the + <a href="f2python9.html">Python 9 Conference paper</a> (F2PY paper). + <dt> December 9, 2000 + <dd> Implemented support for <code>PARAMETER</code> statement. + <dt> November 6, 2000 + <dd> Submitted a paper for 9th Python Conference (accepted). It is available in <a + href="f2python9.html">html</a>, <a href="f2python9.pdf">PDF</a>, + and <a href="f2python9.ps.gz">Gzipped PS</a> formats. + <dt> September 17, 2000 + <dd> Support for F90/95 module data and routines. COMMON block + wrapping is rewritten. New signature file syntax: + <code>pythonmodule</code>. Signature files generated with + f2py-2.264 or earlier, are incompatible (need replacement + <code>module</code> with + <code>pythonmodule</code>). + <dt> September 12, 2000 + <dd> The second public release of <code>f2py</code> is out. See <a + href="Release-2.x.txt">Release notes</a>. + <dt> September 11, 2000 + <dd> Now <code>f2py</code> supports wrapping Fortran 90/95 module routines + (support for F90/95 module data coming soon) + <dt> June 12, 2000 + <dd> Now <code>f2py</code> has a mailing list <a +href="#f2py-users">f2py-users</a> open for discussion. + +</dl> + + +<!-- End of user text --> +<HR> +<ADDRESS> +<A href="http://validator.w3.org/"><IMG border=0 align=right src="/icons/vh40.gif" alt="Valid HTML 4.0!" height=31 width=88></A> +<A href="http://cens.ioc.ee/~pearu/" target="_top">Pearu Peterson</A> +<A href="mailto:pearu (at) ioc.ee"><pearu(at)ioc.ee></A><BR> +<!-- hhmts start --> +Last modified: Mon Dec 3 19:40:26 EET 2001 +<!-- hhmts end --> +</ADDRESS> +<!-- You may want to comment the following line out when the document is final--> +<!-- Check that the reference is right --> +<!--A href="http://validator.w3.org/check?uri=http://cens.ioc.ee/projects/f2py2e/index.html;ss"> Submit this page for validation</A--> + +</BODY> + + +</HTML> diff --git a/numpy/f2py/doc/options.tex b/numpy/f2py/doc/options.tex new file mode 100644 index 000000000..84d9410f8 --- /dev/null +++ b/numpy/f2py/doc/options.tex @@ -0,0 +1,63 @@ + +\section{\fpy command line options} +\label{sec:opts} + +\fpy has the following command line syntax (run \fpy without arguments +to get up to date options!!!): +\begin{verbatim} +f2py [<options>] <fortran files> [[[only:]||[skip:]] <fortran functions> ]\ + [: <fortran files> ...] +\end{verbatim} +where +\begin{description} +\item[\texttt{<options>}] --- the following options are available: + \begin{description} + \item[\texttt{-f77}] --- \texttt{<fortran files>} are in Fortran~77 + fixed format (default). + \item[\texttt{-f90}] --- \texttt{<fortran files>} are in + Fortran~90/95 free format (default for signature files). + \item[\texttt{-fix}] --- \texttt{<fortran files>} are in + Fortran~90/95 fixed format. + \item[\texttt{-h <filename>}] --- after scanning the + \texttt{<fortran files>} write the signatures of Fortran routines + to file \texttt{<filename>} and exit. If \texttt{<filename>} + exists, \fpy quits without overwriting the file. Use + \texttt{-{}-overwrite-signature} to overwrite. + \item[\texttt{-m <modulename>}] --- specify the name of the module + when scanning Fortran~77 codes for the first time. \fpy will + generate Python C/API module source \texttt{<modulename>module.c}. + \item[\texttt{-{}-lower/-{}-no-lower}] --- lower/do not lower the cases + when scanning the \texttt{<fortran files>}. Default when + \texttt{-h} flag is specified/unspecified (that is for Fortran~77 + codes/signature files). + \item[\texttt{-{}-short-latex}] --- use this flag when you want to + include the generated LaTeX document to another LaTeX document. + \item[\texttt{-{}-debug-capi}] --- create a very verbose C/API + code. Useful for debbuging. +% \item[\texttt{-{}-h-force}] --- if \texttt{-h <filename>} is used then +% overwrite the file \texttt{<filename>} (if it exists) and continue +% with constructing the C/API module source. + \item[\texttt{-makefile <options>}] --- run \fpy without arguments + for more information. + \item[\texttt{-{}-use-libs}] --- see \texttt{-makefile}. + \item[\texttt{-{}-overwrite-makefile}] --- overwrite existing + \texttt{Makefile-<modulename>}. + \item[\texttt{-v}] --- print \fpy version number and exit. + \item[\texttt{-pyinc}] --- print Python include path and exit. + \end{description} +\item[\texttt{<fortran files>}] --- are the paths to Fortran files or + to signature files that will be scanned for \texttt{<fortran + functions>} in order to determine their signatures. +\item[\texttt{<fortran functons>}] --- are the names of Fortran + routines for which Python C/API wrapper functions will be generated. + Default is all that are found in \texttt{<fortran files>}. +\item[\texttt{only:}/\texttt{skip:}] --- are flags for filtering + in/out the names of fortran routines to be wrapped. Run \fpy without + arguments for more information about the usage of these flags. +\end{description} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "f2py2e" +%%% End: diff --git a/numpy/f2py/doc/python9.tex b/numpy/f2py/doc/python9.tex new file mode 100644 index 000000000..cda3cd18b --- /dev/null +++ b/numpy/f2py/doc/python9.tex @@ -0,0 +1,1046 @@ +\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 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:<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:
+
+
diff --git a/numpy/f2py/doc/signaturefile.tex b/numpy/f2py/doc/signaturefile.tex new file mode 100644 index 000000000..3cd16d890 --- /dev/null +++ b/numpy/f2py/doc/signaturefile.tex @@ -0,0 +1,368 @@ + +\section{Signature file} +\label{sec:signaturefile} + +The syntax of a signature file is borrowed from the Fortran~90/95 +language specification. Almost all Fortran~90/95 standard constructs +are understood. Recall that Fortran~77 is a subset of Fortran~90/95. +This tool introduces also some new attributes that are used for +controlling the process of Fortran to Python interface construction. +In the following, a short overview of the constructs +used in signature files will be given. + + +\subsection{Module block} +\label{sec:moduleblock} + +A signature file contains one or more \texttt{pythonmodule} blocks. A +\texttt{pythonmodule} block has the following structure: +\begin{verbatim} +python module <modulename> + interface + <routine signatures> + end [interface] + interface + module <F90/95 modulename> + <F90 module data type declarations> + <F90 module routine signatures> + end [module [<F90/95 modulename>]] + end [interface] +end [pythonmodule [<modulename>]] +\end{verbatim} +For each \texttt{pythonmodule} block \fpy will generate a C-file +\texttt{<modulename>module.c} (see step (iii)). (This is not true if +\texttt{<modulename>} contains substring \texttt{\_\_user\_\_}, see +Sec.~\ref{sec:cbmodule} and \texttt{external} attribute). + +\subsection{Signatures of Fortran routines and Python functions} +\label{sec:routineblock} + + +The signature of a Fortran routine has the following structure: +\begin{verbatim} +[<typespec>] function|subroutine <routine name> [([<arguments>])] \ + [result (<entityname>)] + [<argument type declarations>] + [<argument attribute statements>] + [<use statements>] + [<common block statements>] + [<other statements>] +end [function|subroutine [<routine name>]] +\end{verbatim} + +Let us introduce also the signature of the corresponding wrapper +function: +\begin{verbatim} +def <routine name>(<required arguments>[,<optional arguments>]): + ... + return <return variables> +\end{verbatim} + +Before you edit the signature file, you should first decide what is the +desired signature of the corresponding Python function. \fpy offers +many possibilities to control the interface construction process: you +may want to insert/change/remove various attributes in the +declarations of the arguments in order to change the appearance +of the arguments in the Python wrapper function. + +\begin{itemize} +\item +The definition of the \texttt{<argument type declaration>} is +\begin{verbatim} +<typespec> [[<attrspec>]::] <entitydecl> +\end{verbatim} +where +\begin{verbatim} +<typespec> := byte | character[<charselector>] + | complex[<kindselector>] | real[<kindselector>] + | double complex | double precision + | integer[<kindselector>] | logical[<kindselector>] +\end{verbatim} +\begin{verbatim} +<charselector> := *<charlen> | ([len=]<len>[,[kind]<kind>]) + | (kind=<kind>[,len=<len>]) +<kindselector> := *<intlen> | ([kind=]<kind>) +\end{verbatim} +(there is no sense to modify \texttt{<typespec>}s generated by \fpy). +\texttt{<attrspec>} is a comma separated list of attributes (see +Sec.~\ref{sec:attributes}); +\begin{verbatim} +<entitydecl> := <name> [[*<charlen>][(<arrayspec>)] + | [(<arrayspec>)]*<charlen>] + | [/<init_expr>/ | =<init_expr>] [,<entitydecl>] +\end{verbatim} +where \texttt{<arrayspec>} is a comma separated list of dimension +bounds; \texttt{<init\_expr>} is a C-expression (see +Sec.~\ref{sec:C-expr}). If an argument is not defined with +\texttt{<argument type declaration>}, its type is determined by +applying \texttt{implicit} rules (if it is not specifyied, then +standard rules are applied). + +\item The definition of the \texttt{<argument attribute statement>} is +a short form of the \texttt{<argument type declaration>}: +\begin{verbatim} +<attrspec> <entitydecl> +\end{verbatim} + +\item \texttt{<use statement>} is defined as follows +\begin{verbatim} +use <modulename> [,<rename_list> | ,ONLY:<only_list>] +<rename_list> := local_name=>use_name [,<rename_list>] +\end{verbatim} + Currently the \texttt{use} statement is used to link call-back + modules (Sec.~\ref{sec:cbmodule}) and the \texttt{external} + arguments (call-back functions). + +\item \texttt{<common block statement>} is defined as follows +\begin{verbatim} +common /<commonname>/ <shortentitydecl> +\end{verbatim} +where +\begin{verbatim} +<shortentitydecl> := <name> [(<arrayspec>)] [,<shortentitydecl>] +\end{verbatim} +One \texttt{module} block should not contain two or more +\texttt{common} blocks with the same name. Otherwise, the later ones +are ignored. The types of variables in \texttt{<shortentitydecl>} can +be defined in \texttt{<argument type declarations>}. Note that there +you can specify also the array specifications; then you don't need to +do that in \texttt{<shortentitydecl>}. +\end{itemize} + +\subsection{Attributes} +\label{sec:attributes} + +The following attributes are used by \fpy: +\begin{description} +\item[\texttt{optional}] --- the variable is moved to the end of + optional argument list of the wrapper function. Default value of an + optional argument can be specified using \texttt{<init\_expr>} in + \texttt{entitydecl}. You can use \texttt{optional} attribute also for + \texttt{external} arguments (call-back functions), but it is your + responsibility to ensure that it is given by the user if Fortran + routine wants to call it. +\item[\texttt{required}] --- the variable is considered as a required + argument (that is default). You will need this in order to overwrite + the \texttt{optional} attribute that is automatically set when + \texttt{<init\_expr>} is used. However, usage of this attribute + should be rare. +\item[\texttt{dimension(<arrayspec>)}] --- used when the variable is + an array. For unbounded dimensions symbols `\texttt{*}' or + `\texttt{:}' can be used (then internally the corresponding + dimensions are set to -1; you'll notice this when certain exceptions + are raised). +\item[\texttt{external}] --- the variable is a call-back function. \fpy will + construct a call-back mechanism for this function. Also call-back + functions must be defined by their signatures, and there are several + ways to do that. In most cases, \fpy will be able to determine the signatures + of call-back functions from the Fortran source code; then it + builds an additional \texttt{module} block with a name containing + string `\texttt{\_\_user\_\_}' (see Sec.~\ref{sec:cbmodule}) and + includes \texttt{use} statement to the routines signature. Anyway, + you should check that the generated signature is correct. + + Alternatively, you can specify the signature by inserting to the + routines block a ``model'' how the call-back function would be called + from Fortran. For subroutines you should use\\ + \hspace*{2em}\texttt{call <call-back name>(<arguments>)}\\ + and for functions\\% + \hspace*{2em}\texttt{<return value> = <call-back name>(<arguments>)}\\ + The variables in \texttt{<arguments>} and \texttt{<return value>} + must be defined as well. You can use the arguments of the main + routine, for instance. +\item[\texttt{intent(<intentspec>)}] --- this specifies the + ``intention'' of the variable. \texttt{<intentspec>} is a comma + separated list of the following specifications: + \begin{description} + \item[\texttt{in}] --- the variable is considered to be an input + variable (default). It means that the Fortran function uses only + the value(s) of the variable and is assumed not to change it. + \item[\texttt{inout}] --- the variable is considered to be an + input/output variable which means that Fortran routine may change + the value(s) of the variable. Note that in Python only array + objects can be changed ``in place''. (\texttt{intent(outin)} is + \texttt{intent(inout)}.) + \item[\texttt{out}] --- the value of the (output) variable is + returned by the wrapper function: it is appended to the list of + \texttt{<returned variables>}. If \texttt{out} is specified alone, + also \texttt{hide} is assumed. + \item[\texttt{hide}] --- use this if the variable \emph{should not} + or \emph{need not} to be in the list of wrapper function arguments + (not even in optional ones). For example, this is assumed if + \texttt{intent(out)} is used. You can ``hide'' an argument if it + has always a constant value specified in \texttt{<init\_expr>}, + for instance. + \end{description} + The following rules apply: + \begin{itemize} + \item if no \texttt{intent} attribute is specified, \texttt{intent(in)} is + assumed; + \item \texttt{intent(in,inout)} is \texttt{intent(in)}; + \item \texttt{intent(in,hide)}, \texttt{intent(inout,hide)} are \texttt{intent(hide)}; + \item \texttt{intent(out)} is \texttt{intent(out,hide)}; +\item \texttt{intent(inout)} is NOT \texttt{intent(in,out)}. + \end{itemize} + In conclusion, the following combinations are ``minimal'': + \texttt{intent(in)}, \texttt{intent(inout)}, \texttt{intent(out)}, + \texttt{intent(hide)}, \texttt{intent(in,out)}, and + \texttt{intent(inout,out)}. +\item[\texttt{check([<C-booleanexpr>])}] --- if + \texttt{<C-booleanexpr>} evaluates to zero, an exception is raised + about incorrect value or size or any other incorrectness of the + variable. If \texttt{check()} or \texttt{check} is used then \fpy + will not try to guess the checks automatically. +\item[\texttt{depend([<names>])}] --- the variable depends on other + variables listed in \texttt{<names>}. These dependence relations + determine the order of internal initialization of the variables. If + you need to change these relations then be careful not to break the + dependence relations of other relevant variables. If + \texttt{depend()} or \texttt{depend} is used then \fpy will not try + to guess the dependence relations automatically. +\item[\texttt{note(<LaTeX text>)}] --- with this attribute you can + include human readable documentation strings to the LaTeX document + that \fpy generates. Do not insert here information that \fpy can + establish by itself, such as, types, sizes, lengths of the + variables. Here you can insert almost arbitrary LaTeX text. Note + that \texttt{<LaTeX text>} is mainly used inside the LaTeX + \texttt{description} environment. Hint: you can use + \texttt{\bs{}texttt\{<name>\}} for typesetting variable \texttt{<name>} + in LaTeX. In order to get a new line to the LaTeX document, use + \texttt{\bs{}n} followed by a space. For longer text, you may want + to use line continuation feature of Fortran 90/95 language: set + \texttt{\&} (ampersand) + to be the last character in a line. +\item[\texttt{parameter}] --- the variable is parameter and it must + have a value. If the parameter is used in dimension specification, + it is replaced by its value. (Are there any other usages of + parameters except in dimension specifications? Let me know and I'll + add support for it). +\end{description} + + +\subsection{C-expressions} +\label{sec:C-expr} + +The signature of a routine may contain C-expressions in +\begin{itemize} +\item \texttt{<init\_expr>} for initializing particular variable, or in +\item \texttt{<C-booleanexpr>} of the \texttt{check} attribute, or in +\item \texttt{<arrayspec>} of the \texttt{dimension} attribute. +\end{itemize} +A C-expression may contain +\begin{itemize} +\item standard C-statement, +\item functions offered in \texttt{math.h}, +\item previously initialized variables (study +the dependence relations) from the argument list, and +\item the following CPP-macros: + \begin{description} + \item[\texttt{len(<name>)}] --- the length of an array \texttt{<name>}; + \item[\texttt{shape(<name>,<n>)}] --- the $n$-th dimension of an array + \texttt{<name>}; + \item[\texttt{rank(<name>)}] --- the rank of an array \texttt{<name>}; + \item[\texttt{slen(<name>)}] --- the length of a string \texttt{<name>}. + \end{description} +\end{itemize} + + +In addition, when initializing arrays, an index vector \texttt{int + \_i[rank(<name>)];} +is available: \texttt{\_i[0]} refers to +the index of the first dimension, \texttt{\_i[1]} to the index of +the second dimension, etc. For example, the argument type declaration\\ +\hspace*{2em}\texttt{integer a(10) = \_i[0]}\\ +is equivalent with the following Python statement\\ +\hspace*{2em}\texttt{a = array(range(10))} + + +\subsection{Required/optional arguments} +\label{sec:reqoptargs} + +When \texttt{optional} attribute is used (including the usage of +\texttt{<init\_expr>} without the \texttt{required} attribute), the +corresponding variable in the argument list of a Fortran routine is +appended to the optional argument list of the wrapper function. + +For optional array argument all dimensions must be bounded (not +\texttt{(*)} or \texttt{(:)}) and defined at the time of +initialization (dependence relations). + +If the \texttt{None} object is passed in in place of a required array +argument, it will be considered as optional: that is, the memory is +allocated (of course, if it has unbounded dimensions, an exception +will be raised), and if \texttt{<init\_expr>} is defined, +initialization is carried out. + + +\subsection{Internal checks} +\label{sec:intchecks} + +All array arguments are checked against the correctness of their rank. +If there is a mismatch, \fpy attempts to fix that by constructing an +array with a correct rank from the given array argument (there will be +no performance hit as no data is copied). The freedom to do so is +given only if some dimensions are unbounded or their value is 1. An +exception is raised when the sizes will not match. + +All bounded dimensions of an array are checked to be larger or equal +to the dimensions specified in the signature. + +So, you don't need to give explicit \texttt{check} attributes to check +these internal checks. + + +\subsection{Call-back modules} +\label{sec:cbmodule} + +A Fortran routine may have \texttt{external} arguments (call-back +functions). The signatures of the call-back functions must be defined +in a call-back \texttt{module} block (its name contains +\texttt{\_\_user\_\_}), in general; other possibilities are described +in the \texttt{external} attribute specification (see +Sec.~\ref{sec:attributes}). For the signatures of call-back +functions the following restrictions apply: +\begin{itemize} +\item Attributes \texttt{external}, \texttt{check(...)}, and + initialization statements are ignored. +\item Attribute \texttt{optional} is used only for changing the order + of the arguments. +\item For arrays all dimension bounds must be specified. They may be + C-expressions containing variables from the argument list. + Note that here CPP-macros \texttt{len}, \texttt{shape}, + \texttt{rank}, and \texttt{slen} are not available. +\end{itemize} + + +\subsection{Common blocks} +\label{sec:commonblocks} + +All fields in a common block are mapped to arrays of appropriate sizes +and types. Scalars are mapped to rank-0 arrays. For multi-dimensional +fields the corresponding arrays are transposed. In the type +declarations of the variables representing the common block fields, +only \texttt{dimension(<arrayspec>)}, \texttt{intent(hide)}, and +\texttt{note(<LaTeX text>)} attributes are used, others are ignored. + +\subsection{Including files} +\label{sec:include} + +You can include files to the signature file using +\begin{verbatim} +include '<filename>' +\end{verbatim} +statement. It can be used in any part of the signature file. +If the file \texttt{<filename>} does not exists or it is not in the path, +the \texttt{include} line is ignored. + +\subsection{\fpy directives} +\label{sec:directives} + +You can insert signature statements directly to Fortran source codes +as comments. Anything that follows \texttt{<comment char>f2py} is +regarded as normal statement for \fpy. + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "f2py2e" +%%% End: + diff --git a/numpy/f2py/doc/using_F_compiler.txt b/numpy/f2py/doc/using_F_compiler.txt new file mode 100644 index 000000000..3067f0776 --- /dev/null +++ b/numpy/f2py/doc/using_F_compiler.txt @@ -0,0 +1,147 @@ + +Title: Wrapping F compiled Fortran 90 modules with F2PY + ================================================ + +Rationale: The F compiler does not support external procedures which + makes it impossible to use it in F2PY in a normal way. + This document describes a workaround to this problem so + that F compiled codes can be still wrapped with F2PY. + +Author: Pearu Peterson +Date: May 8, 2002 + +Acknowledgement: Thanks to Siegfried Gonzi who hammered me to produce + this document. + +Normally wrapping Fortran 90 modules to Python using F2PY is carried +out with the following command + + f2py -c -m fun foo.f90 + +where file foo.f90 contains, for example, + +module foo + public :: bar + contains + subroutine bar (a) + integer,intent(inout) :: a + print *,"Hello from foo.bar" + print *,"a=",a + a = a + 5 + print *,"a=",a + end subroutine bar +end module foo + +Then with a supported F90 compiler (running `f2py -c --help-compiler' +will display the found compilers) f2py will generate an extension +module fun.so into the current directory and the Fortran module foo +subroutine bar can be called from Python as follows + +>>> import fun +>>> print fun.foo.bar.__doc__ +bar - Function signature: + bar(a) +Required arguments: + a : in/output rank-0 array(int,'i') + +>>> from Numeric import array +>>> a = array(3) +>>> fun.foo.bar(a) + Hello from foo.bar + a= 3 + a= 8 +>>> a +8 +>>> + +This works nicely with all supported Fortran compilers. + +However, the F compiler (http://www.fortran.com/F/compilers.html) is +an exception. Namely, the F compiler is designed to recognize only +module procedures (and main programs, of course) but F2PY needs to +compile also the so-called external procedures that it generates to +facilitate accessing Fortran F90 module procedures from C and +subsequently from Python. As a result, wrapping F compiled Fortran +procedures to Python is _not_ possible using the simple procedure as +described above. But, there is a workaround that I'll describe below +in five steps. + +1) Compile foo.f90: + + F -c foo.f90 + +This creates an object file foo.o into the current directory. + +2) Create the signature file: + + f2py foo.f90 -h foo.pyf + +This creates a file foo.pyf containing + +module foo ! in foo.f90 + real public :: bar + subroutine bar(a) ! in foo.f90:foo + integer intent(inout) :: a + end subroutine bar +end module foo + +3) Open the file foo.pyf with your favorite text editor and change the + above signature to + +python module foo + interface + subroutine bar(a) + fortranname foo_MP_bar + intent(c) bar + integer intent(in,out) :: a + end subroutine bar + end interface +end python module foo + +The most important modifications are + + a) adding `python' keyword everywhere before the `module' keyword + + b) including an `interface' block around the all subroutine blocks. + + c) specifying the real symbol name of the subroutine using + `fortranname' statement. F generated symbol names are in the form + <module name>_MP_<subroutine name> + + d) specifying that subroutine is `intent(c)'. + +Notice that the `intent(inout)' attribute is changed to +`intent(in,out)' that instructs the wrapper to return the modified +value of `a'. + +4) Build the extension module + + f2py -c foo.pyf foo.o --fcompiler=Gnu /opt/F/lib/quickfit.o \ + /opt/F/lib/libf96.a + +This will create the extension module foo.so into the current +directory. Notice that you must use Gnu compiler (gcc) for linking. +And the paths to F specific object files and libraries may differ for +your F installation. + +5) Finally, we can call the module subroutine `bar' from Python + +>>> import foo +>>> print foo.bar.__doc__ +bar - Function signature: + a = bar(a) +Required arguments: + a : input int +Return objects: + a : int + +>>> foo.bar(3) +8 +>>> + +Notice that the F compiled module procedures are called as ordinary +external procedures. Also I/O seems to be lacking for F compiled +Fortran modules. + +Enjoy, + Pearu diff --git a/numpy/f2py/doc/win32_notes.txt b/numpy/f2py/doc/win32_notes.txt new file mode 100644 index 000000000..1b7b9029c --- /dev/null +++ b/numpy/f2py/doc/win32_notes.txt @@ -0,0 +1,85 @@ +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 [<options>] <fortran files> [[[only:]||[skip:]] \
+ <fortran functions> ] \
+ [: <fortran files> ...]
+ ...
+
+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
+
|
