1、F2PY 用戶指南和參考手冊(cè)作者Author:Pearu PetersonContact:Web site:Date:2005-01-30Revision:1.25譯者翻譯：cpythonerEmail:Blog:日期：2005-03-10版本1.25-1貢獻(xiàn)者目 錄1引言22三種封裝方法 開始22.1快速方法32.2聰明方法42.3既快且聰明的方法53簽名文件63.1Python module block73.2Fortran/C 例程簽名73.2.1類型聲明（Type declarations）83.2.2語(yǔ)句（Statements）83.2.3A

2、ttributes113.3擴(kuò)展153.3.1F2PY指令153.3.2C語(yǔ)言表達(dá)式163.3.3Multiline blocks174在Python中使用綁定174.1標(biāo)量參數(shù)（或數(shù)值參數(shù)）184.2字符串參數(shù)194.3數(shù)組參數(shù)204.4回調(diào)參數(shù)234.5Common blocks264.6Fortran 90 module data284.6.1Allocatable arrays295使用F2PY305.1命令f2py305.2Python module f2py2e346使用scipy_distutils356.1Scipy_distutils 0.2.2及更高版本366.2Scipy

3、_distutils pre 0.2.2367F2PY的擴(kuò)展用法377.1向F2PY產(chǎn)生的模塊中添加自寫的函數(shù)377.2修改F2PY生成模塊的字典381 引言F2PYFortran to Python interface generator項(xiàng)目的目的是要在Python和Fortran語(yǔ)言之間提供一個(gè)連接。F2PY是一個(gè)Python包（包含一個(gè)命令行工具f2py和一個(gè)模塊f2py2e），用來建立Python C/API擴(kuò)展模塊，從而能夠： 調(diào)用Fortran 77/90/95外部子程序、Fortran 90/95模塊子程序以及C函數(shù)； 訪問Fortran 77 COMMON blocks和For

4、tran 90/95 module 數(shù)據(jù)，包括allocatable arrays。2 三種封裝方法 開始用F2PY把Fortran 或 C函數(shù)封裝成Python 包括下列步驟： 創(chuàng)建簽名文件，包含：對(duì)Fortran或C函數(shù)封裝器的描述，也稱為函數(shù)簽名。在Fortran routines的情況下，F(xiàn)2PY通過掃描Fortran源碼，從而收集創(chuàng)建函數(shù)封裝器所需要的所有相關(guān)信息。 （可選）編輯F2PY所創(chuàng)建的簽名文件，以優(yōu)化函數(shù)封裝器，使之更“聰明”、更加“Python化”。 F2PY讀取簽名文件，生成一個(gè)Python C/API模塊，該模塊包含F(xiàn)ortran/C/Python綁定信息。 F2PY

5、編譯所有的源文件，建立包含封裝器的擴(kuò)展模塊。在建立擴(kuò)展模塊時(shí)，F(xiàn)2PY使用了scipy_distutils包，它支持大量的Fortran編譯器。上述步驟可以在一條命令中執(zhí)行，也可以一步一步順序執(zhí)行，其中某些步驟可以忽略或者同其它步驟組合使用，視具體情況而定。下面介紹3種使用F2PY的典型方法。以下面的Fortran 77代碼為例說明。C FILE: FIB1.F SUBROUTINE FIB(A,N)CC CALCULATE FIRST N FIBONACCI NUMBERSC INTEGER N REAL*8 A(N) DO I=1,N IF (I.EQ.1) THEN A(I) = 0.0

6、D0 ELSEIF (I.EQ.2) THEN A(I) = 1.0D0 ELSE A(I) = A(I-1) + A(I-2) ENDIF ENDDO ENDC END 2.1 快速方法把Fortran 子程序FIB封裝為Python函數(shù)的最快的方法是運(yùn)行： F2py c fib1.f m fib1該命令在當(dāng)前目錄下建立一個(gè)擴(kuò)展模塊fib1.pyd?，F(xiàn)在，在Python中就可以訪問Fortran子程序FIB了： import Numeric import fib1 print fib1.fib._doc_fib - Function signature: fib(a,n)Required a

7、rguments: a : input rank-1 array(d) with bounds (n)Optional arguments: n := len(a) input int a=Numeric.zeros(8,d) fib1.fib(a) print a 0. 1. 1. 2. 3. 5. 8. 13.注： F2PY發(fā)現(xiàn)第2個(gè)參數(shù)n是第一個(gè)數(shù)組參數(shù)的維數(shù)，因?yàn)槿笔∏闆r下所有參數(shù)都是input-only的，因此F2PY得出結(jié)論，n是可選參數(shù)，它的缺省值為len(a)。 對(duì)于可選參數(shù)n，可以使用不同的值。 a1=Numeric.zeros(8,d) fib1.fib(a1,6) pri

8、nt a1 0. 1. 1. 2. 3. 5. 0. 0.但當(dāng)它和數(shù)組參數(shù)a不相容時(shí)，會(huì)拋出一個(gè)異常： fib1.fib(a,10)fib:n=10Traceback (most recent call last): File , line 1, in ?fib.error: (len(a)=n) failed for 1st keyword n 這說明F2PY具有一個(gè)有用的特征，即，F(xiàn)2PY對(duì)相關(guān)參數(shù)間的相容性進(jìn)行初步的檢查，以避免不可預(yù)期的崩潰。 當(dāng)使用Numeric array 作為輸入數(shù)組參數(shù)時(shí)，C指針會(huì)被直接傳給Fortran。否則，F(xiàn)2PY就復(fù)制輸入數(shù)組，然后將副本的C指針傳給Fo

9、rtran子程序。結(jié)果，F(xiàn)ortran子程序?qū)斎霐?shù)組的任何改變都不會(huì)影響原先的參數(shù)。示例如下： a=Numeric.ones(8,i) fib1.fib(a) print a1 1 1 1 1 1 1 1這顯然不是我們所期望的結(jié)果。F2PY提供了intent(inplace)屬性，它能改變輸入數(shù)組的屬性，使得Fortran 例程所作的任何改變都對(duì)輸入?yún)?shù)有效。例如，如果你指定 intent(inplace) a，上面的例子就會(huì)變?yōu)椋海?a=Numeric.ones(8,i) fib1.fib(a) print a 0. 1. 1. 2. 3. 5. 8. 13.然而，推薦使用intent(o

10、ut)屬性，來把fortran例程所作的改變反饋給python，這個(gè)方案更有效、更清晰。 在python中使用Fib1.fib與在Fortran中使用FIB非常相似。然而，在python中使用in situ output 參數(shù)是不太好的風(fēng)格，因?yàn)閜ython沒有安全機(jī)制處理錯(cuò)誤的參數(shù)類型。當(dāng)使用Fortran和C時(shí)，編譯器在編譯期間就會(huì)發(fā)現(xiàn)類型不匹配，而python必須在運(yùn)行期間才進(jìn)行類型檢查。因此，在python中使用in situ output參數(shù)會(huì)使查找bug變得困難，更不要說在進(jìn)行必須的類型檢查時(shí)代碼可讀性差了。雖然前面演示的封裝方法非常簡(jiǎn)單易懂，但它有幾個(gè)缺點(diǎn)，這都?xì)w因于F2PY無法

11、確定參數(shù)的實(shí)際目的它是輸入?yún)?shù)還是輸出參數(shù)，還是既為輸入又為輸出，又或其它？因此，F(xiàn)2PY假定在缺省情況下所有參數(shù)都是輸入?yún)?shù)。實(shí)際上，有辦法讓F2PY知道函數(shù)參數(shù)的實(shí)際目的，然后產(chǎn)生更加Python化的封裝器。2.2 聰明方法讓我們按照下面步驟封裝Fortran函數(shù)。 首先，運(yùn)行命令f2py fib1.f -m fib2 -h fib1.pyf創(chuàng)建簽名文件，保存為fib1.pyf，其內(nèi)容如下：! -*- f90 -*-python module fib2 ! in interface ! in :fib2 subroutine fib(a,n) ! in :fib2:fib1.f real*

12、8 dimension(n) : a integer optional,check(len(a)=n),depend(a) : n=len(a) end subroutine fib end interface end python module fib2! This auto-generated with f2py (version:2.28.198-1366).! See 接著，告訴F2PY參數(shù)n是一個(gè)輸入?yún)?shù)（使用intent(in)屬性），調(diào)用Fortran函數(shù)FIB所產(chǎn)生的結(jié)果應(yīng)該返回給python（使用intent(out)屬性）。此外，數(shù)組a應(yīng)該根據(jù)輸入?yún)?shù)n動(dòng)態(tài)創(chuàng)建（使用dep

13、end(n)屬性以說明依賴關(guān)系）。修改后的fib1.pyf（另存為fib2.pyf）內(nèi)容如下：! -*- f90 -*-python module fib2 interface subroutine fib(a,n) real*8 dimension(n),intent(out),depend(n) : a integer intent(in) : n end subroutine fib end interface end python module fib2 最后，運(yùn)行f2py -c fib2.pyf fib1.f建立擴(kuò)展模塊In python： import fib2 print fib

14、2.fib._doc_fib - Function signature: a = fib(n)Required arguments: n : input intReturn objects: a : rank-1 array(d) with bounds (n) print fib2.fib(8) 0. 1. 1. 2. 3. 5. 8. 13.注釋： 很明顯，fib2.fib更符合Fortran子程序FIB的目的，給定n，fib2.fib返回一個(gè)前n個(gè)菲波拉契數(shù)的Numericarray。新的python簽名fib2.fib也消除了簽名fib1.fib時(shí)遇到的那種令人驚訝的現(xiàn)象。 注意，在缺

15、省情況下，單獨(dú)使用intent(out)也隱含了intent(hide)。Intent(hide)屬性指定的參數(shù)不出現(xiàn)在封裝器函數(shù)的參數(shù)列表中。2.3 既快且聰明的方法聰明的方法適合封裝那些不能修改的Fortran代碼（比如，第三方的代碼）。然而，F(xiàn)ortran代碼如果可以編輯，那么在多數(shù)情況下可以跳過生成中間簽名文件這一步。也就是說，可以使用F2PY指令將F2PY所特有的屬性直接插入到Fortran源代碼中。F2PY指令是一條特別的注釋行，F(xiàn)ortran編譯器忽略它，但F2PY會(huì)像普通行那樣進(jìn)行處理。下面是修改后的Fortran源代碼，保存為fib3.f：C FILE: FIB3.F SUB

16、ROUTINE FIB(A,N)CC CALCULATE FIRST N FIBONACCI NUMBERSC INTEGER N REAL*8 A(N)Cf2py intent(in) nCf2py intent(out) aCf2py depend(n) a DO I=1,N IF (I.EQ.1) THEN A(I) = 0.0D0 ELSEIF (I.EQ.2) THEN A(I) = 1.0D0 ELSE A(I) = A(I-1) + A(I-2) ENDIF ENDDO ENDC END 現(xiàn)在，可以運(yùn)行f2py -c -m fib3 fib3.f創(chuàng)建擴(kuò)展模塊。注意封裝器函數(shù)FIB

17、同前面例子一樣“聰明”： import fib3 print fib3.fib._doc_fib - Function signature: a = fib(n)Required arguments: n : input intReturn objects: a : rank-1 array(d) with bounds (n) print fib3.fib(8) 0. 1. 1. 2. 3. 5. 8. 13.3 簽名文件簽名文件（.pyf文件）的語(yǔ)法借自于Fortran90/95語(yǔ)言規(guī)范，它幾乎能夠理解Fortran90/95所有的標(biāo)準(zhǔn)結(jié)構(gòu)，包括free和fixed format。F2PY

18、還對(duì)Fortran 90/95語(yǔ)言規(guī)范作了一些擴(kuò)展，以幫助設(shè)計(jì)Fortran到Python的接口，使之更Python化（Pythonic）。簽名文件可以包含任意Fortran代碼（因此，F(xiàn)ortran代碼可以看作是簽名文件）。對(duì)于那些與建立接口無關(guān)的Fortran結(jié)構(gòu)，F(xiàn)2PY只是將之忽略掉，這其中也包括語(yǔ)法錯(cuò)誤。因此，要注意不要有任何的語(yǔ)法錯(cuò)誤（So，be careful not making ones）。簽名文件的內(nèi)容通常是大小寫敏感的，在掃描Fortran代碼生成簽名文件時(shí)，F(xiàn)2PY自動(dòng)將字符轉(zhuǎn)換為小寫。在multi-line blocks中的代碼或使用-no-lower選項(xiàng)時(shí)除外。3.

19、1 Python module block簽名文件包含一個(gè)（推薦）或多個(gè)python module blocks。Python module blocks用來描述F2PY所生成的Python/C擴(kuò)展模塊module.c 的內(nèi)容。如果包含子字符串_user_，那么相應(yīng)的python module block描述的是回調(diào)函數(shù)的簽名。Python module block 結(jié)構(gòu)如下：python module . interface end interface . interface module end module end interface .end python module 內(nèi)為可選部分，

20、表示一個(gè)或多個(gè)前面部分3.2 Fortran/C 例程簽名Fortran例程簽名的結(jié)構(gòu)如下： function | subroutine ( ) result ( ) end function | subroutine F2PY根據(jù)例程簽名產(chǎn)生如下的Python/C擴(kuò)展函數(shù)：def (,): . return Fortran block data的簽名結(jié)構(gòu)如下：block data end block data 3.2.1 類型聲明（Type declarations）參數(shù)/變量的類型聲明部分定義如下： : 這里 := byte | character | complex | real | d

21、ouble complex | double precision | integer | logical := * | ( len= , kind= ) | ( kind= , len= ) := * | ( kind= ) := * ( ) | ( ) * | / / | = , 其中 是用逗號(hào)分隔的屬性列表; 是用逗號(hào)分隔的維數(shù)邊界列表; 是C表達(dá)式 對(duì)整數(shù)類型而言，可以是負(fù)整數(shù)，這時(shí)integer* 表示unsigned C integers. 如果某個(gè)參數(shù)沒有，其類型由參數(shù)名的隱含規(guī)則決定。3.2.2 語(yǔ)句（Statements） Attribute statements: 是沒有的

22、。另外，在 an attribute statement 中不能 use other attributes, 也只能是a list of names. Use statements: 部分的定義是：use , | , ONLY : 這里 := = , 目前，use statement只用于連接回調(diào)模塊（call-back modules ）和外部參數(shù) (回調(diào)函數(shù)), 參見 Call-back arguments. Common block statements: 部分的定義是：common / / 其中 := ( ) , 一個(gè) python module block不應(yīng)包含二個(gè)或二個(gè)以上的同名

23、common blocks，否則，后面的common blocks將會(huì)被忽略。 中的變量類型用定義。要注意的是相應(yīng)的 可能包含array specifications，這樣的話就不必在指定了。 Other statements: 部分是指所有前面未提到的其它Fortran語(yǔ)言結(jié)構(gòu)，除了以下情況外，F(xiàn)2PY都予以忽略不作處理。call statements and function calls of external arguments (more details?); n include statementsinclude include 如果文件 不存在，則忽略該include statem

24、ent，否則，文件 is included to a signature file. include statements 能在簽名文件的任意部分使用, 在 Fortran/C routine signature blocks的外面也可以使用。n implicit statementsimplicit noneimplicit where := ( )如果未用聲明變量類型，那么用隱含規(guī)則確定變量類型。缺省隱含規(guī)則給定如下：implicit real (a-h,o-z,$_), integer (i-m)n entry statementsentry ()F2PY generates wrapp

25、ers to all entry names using the signature of the routine block.技巧：entry statement can be used to describe the signature of an arbitrary routine allowing F2PY to generate a number of wrappers from only one routine block signature. There are few restrictions while doing this: fortranname cannot be us

26、ed, callstatement and callprotoargument can be used only if they are valid for all entry routines, etc.此外, F2PY 還引入了下列statements:n threadsafe Use Py_BEGIN_ALLOW_THREADS . Py_END_ALLOW_THREADS block around the call to Fortran/C function.n callstatement Replace F2PY generated call statement to Fortran

27、/C function with . The wrapped Fortran/C function is available as (*f2py_func). To raise an exception, set f2py_success = 0 in .n callprotoargument When callstatement statement is used then F2PY may not generate proper prototypes for Fortran/C functions (because may contain any function calls and F2

28、PY has no way to determine what should be the proper prototype). With this statement you can explicitely specify the arguments of the corresponding prototype:extern FUNC_F(,)();n fortranname You can use arbitrary for a given Fortran/C function. Then you have to specify with this statement.If fortran

29、name statement is used without then a dummy wrapper is generated.n usercode When used inside python module block, then given C code will be inserted to generated C/API source just before wrapper function definitions. Here you can define arbitrary C functions to be used in initialization of optional

30、arguments, for example. If usercode is used twise inside python module block then the second multi-line block is inserted after the definition of external routines.When used inside , then given C code will be inserted to the corresponding wrapper function just after declaring variables but before an

31、y C statements. So, usercode follow-up can contain both declarations and C statements.When used inside the first interface block, then given C code will be inserted at the end of the initialization function of the extension module. Here you can modify extension modules dictionary. For example, for d

32、efining additional variables etc.n pymethoddef Multiline block will be inserted to the definition of module methods PyMethodDef-array. It must be a comma-separated list of C arrays (see Extending and Embedding Python documentation for details). pymethoddef statement can be used only inside python mo

33、dule block.3.2.3 AttributesF2PY使用了下列屬性: 可選（optional）相應(yīng)的參數(shù)被移到列表的末尾。 可選參數(shù)的缺省值由指定，請(qǐng)參見entitydecl 的定義。 缺省值必須是有效的C語(yǔ)言表達(dá)式。在使用 時(shí)，F(xiàn)2PY自動(dòng)設(shè)為可選屬性。可選數(shù)組參數(shù)的所有維數(shù)都必須是有界的。 必須（required） 相應(yīng)的參數(shù)被視為必須的參數(shù)，這是缺省屬性，只有當(dāng)使用了，而你又要禁用自動(dòng)optional設(shè)置時(shí)，才需要指定required。如果 Python None object被設(shè)置為required argument，那么該參數(shù)被視為可選的。就是說，in the case o

34、f array argument, the memory is allocated. And if is given, the corresponding initialization is carried out. dimension() 相應(yīng)的變量視為數(shù)組，其維數(shù)由指定。 intent() This specifies the intention of the corresponding argument. is a comma separated list of the following keys:n in The argument is considered as an input-

35、only argument. 參數(shù)值傳給 Fortran/C function ，該函數(shù)不能改變參數(shù)的值。n inout The argument is considered as an input/output or in situ output argument. intent(inout) arguments can be only contiguous Numeric arrays with proper type and size. Here contiguous can be either in Fortran or C sense. The latter one coincide

36、s with the contiguous concept used in Numeric and is effective only if intent(c) is used. Fortran-contiguousness is assumed by default.通常不推薦使用intent(inout)，而代之以 intent(in,out)。 See also intent(inplace) attribute.n inplace The argument is considered as an input/output or in situ output argument. inte

37、nt(inplace) arguments must be Numeric arrays with proper size. If the type of an array is not proper or the array is non-contiguous then the array will be changed in-place to fix the type and make it contiguous.通常也不推薦使用intent(inplace). For example, when slices have been taken from an intent(inplace)

38、 argument then after in-place changes, slices data pointers may point to unallocated memory area.n out The argument is considered as an return variable. It is appended to the list. Using intent(out) sets intent(hide) automatically, unless also intent(in) or intent(inout) were used.缺省情況下，返回的多維數(shù)組是Fort

39、ran-contiguous。如果使用了intent(c), 那么返回的多維數(shù)組則是C-contiguous。n hide The argument is removed from the list of required or optional arguments. Typically intent(hide) is used with intent(out) or when completely determines the value of the argument like in the following example:integer intent(hide),depend(a)

40、: n = len(a)real intent(in),dimension(n) : a n c The argument is treated as a C scalar or C array argument. In the case of a scalar argument, its value is passed to C function as a C scalar argument (recall that Fortran scalar arguments are actually C pointer arguments). In the case of an array argu

41、ment, the wrapper function is assumed to treat multi-dimensional arrays as C-contiguous arrays.There is no need to use intent(c) for one-dimensional arrays, no matter if the wrapped function is either a Fortran or a C function. This is because the concepts of Fortran- and C-contiguousness overlap in

42、 one-dimensional cases.If intent(c) is used as an statement but without entity declaration list, then F2PY adds intent(c) attibute to all arguments.Also, when wrapping C functions, one must use intent(c) attribute for in order to disable Fortran specific F_FUNC(.,.) macros.n cache The argument is tr

43、eated as a junk of memory. No Fortran nor C contiguousness checks are carried out. Using intent(cache) makes sense only for array arguments, also in connection with intent(hide) or optional attributes.n copy Ensure that the original contents of intent(in) argument is preserved. Typically used in con

44、nection with intent(in,out) attribute. F2PY creates an optional argument overwrite_ with the default value 0.n overwrite The original contents of the intent(in) argument may be altered by the Fortran/C function. F2PY creates an optional argument overwrite_ with the default value 1.n out= Replace the

45、 return name with in the _doc_ string of a wrapper function.n callback Construct an external function suitable for calling Python function from Fortran. intent(callback) must be specified before the corresponding external statement. If argument is not in argument list then it will be added to Python

46、 wrapper but is not used when calling Fortran function.Use intent(callback) in situations where a Fortran/C code assumes that a user implements a function with given prototype and links it to an executable.n aux Define auxiliary C variable in F2PY generated wrapper function. Useful to save parameter

47、 values so that they can be accessed in initialization expression of other variables. Note that intent(aux) silently implies intent(c).The following rules apply: If no intent(in | inout | out | hide) is specified, intent(in) is assumed. intent(in,inout) is intent(in). intent(in,hide) or intent(inout,hide) is intent(hide). intent(out) is intent(out,hide) unless intent(in) or intent(inout) is specified. If intent(copy) or intent(overwrite) is used, then an additional