F2PY 示例#

以下是 F2PY 用法的一些示例。此列表并不全面,但可以用作包装您自己的代码时的起点。

F2PY 演练:基本扩展模块#

为基本扩展模块创建源代码#

考虑以下子例程,包含在名为add.f

C
      SUBROUTINE ZADD(A,B,C,N)
C
      DOUBLE COMPLEX A(*)
      DOUBLE COMPLEX B(*)
      DOUBLE COMPLEX C(*)
      INTEGER N
      DO 20 J = 1, N
         C(J) = A(J)+B(J)
 20   CONTINUE
      END

该例程只是将两个连续数组中的元素相加,并将结果放入第三个数组中。所有三个数组的内存必须由调用例程提供。 f2py 可以自动生成该例程的一个非常基本的接口:

python -m numpy.f2py -m add add.f

addmodule.c该命令将生成一个在当前目录中命名的扩展模块。现在可以像任何其他扩展模块一样从 Python 编译和使用此扩展模块。

创建编译的扩展模块#

笔记

此用法在很大程度上取决于numpy.distutils,有关更多详细信息,请参阅F2PY 和构建系统

您还可以让 f2py 与生成的扩展模块一起编译,add.f只留下可以从 Python 导入的共享库扩展文件:

python -m numpy.f2py -c -m add add.f

此命令生成与您的平台兼容的 Python 扩展模块。然后可以从 Python 导入该模块。它将包含 中每个子例程的方法add。每个方法的文档字符串包含有关如何调用模块方法的信息:

>>> import add
>>> print(add.zadd.__doc__)
zadd(a,b,c,n)

Wrapper for ``zadd``.

Parameters
----------
a : input rank-1 array('D') with bounds (*)
b : input rank-1 array('D') with bounds (*)
c : input rank-1 array('D') with bounds (*)
n : input int

改进基本界面#

默认界面是 Fortran 代码到 Python 的直译。 Fortran 数组参数将转换为 NumPy 数组,并且整数参数应映射为C整数。该接口将尝试将所有参数转换为其所需的类型(和形状),如果不成功则发出错误。然而,由于f2py对参数的语义一无所知(例如,它C是一个输出并且n应该真正匹配数组大小),因此可能会以导致 Python 崩溃的方式滥用此函数。例如:

>>> add.zadd([1, 2, 3], [1, 2], [3, 4], 1000)

在大多数系统上会导致程序崩溃。在幕后,列表被转换为数组,但随后底层add函数被告知循环超出分配内存的边界。

为了改进界面,f2py支持指令。这是通过构建签名文件来完成的。通常最好从f2py该文件中生成的接口开始,这些接口对应于默认行为。要f2py生成接口文件,请使用以下-h 选项:

python -m numpy.f2py -h add.pyf -m add add.f

该命令add.pyf在当前目录中创建文件。该文件对应的部分zadd是:

subroutine zadd(a,b,c,n) ! in :add:add.f
   double complex dimension(*) :: a
   double complex dimension(*) :: b
   double complex dimension(*) :: c
   integer :: n
end subroutine zadd

通过放置意图指令和检查代码,可以对接口进行相当多的清理,因此 Python 模块方法既更易于使用,又对格式错误的输入更加健壮。

subroutine zadd(a,b,c,n) ! in :add:add.f
   double complex dimension(n) :: a
   double complex dimension(n) :: b
   double complex intent(out),dimension(n) :: c
   integer intent(hide),depend(a) :: n=len(a)
end subroutine zadd

意图指令intent(out)用于告诉f2py这c是一个输出变量,并且应该在传递给底层代码之前由接口创建。 Intent(hide) 指令告诉 f2py 不允许用户指定变量 ,n而是从 的大小中获取它a。 dependent( a) 指令有必要告诉 f2py n 的值取决于输入 a (这样在创建变量 a 之前它不会尝试创建变量 n)。

修改后,通过编译和add.pyf即可生成新的Python模块文件:add.fadd.pyf

python -m numpy.f2py -c add.pyf add.f

新界面的文档字符串是:

>>> import add
>>> print(add.zadd.__doc__)
c = zadd(a,b)

Wrapper for ``zadd``.

Parameters
----------
a : input rank-1 array('D') with bounds (n)
b : input rank-1 array('D') with bounds (n)

Returns
-------
c : rank-1 array('D') with bounds (n)

现在,可以以更健壮的方式调用该函数:

>>> add.zadd([1, 2, 3], [4, 5, 6])
array([5.+0.j, 7.+0.j, 9.+0.j])

请注意发生的自动转换为正确的格式。

在 Fortran 源代码中插入指令#

上一节的健壮接口也可以通过将变量指令作为特殊注释放置在原始 Fortran 代码中来自动生成。

笔记

对于正在积极开发 Fortran 代码的项目,这可能是首选。

因此,如果源代码修改为包含:

C
      SUBROUTINE ZADD(A,B,C,N)
C
CF2PY INTENT(OUT) :: C
CF2PY INTENT(HIDE) :: N
CF2PY DOUBLE COMPLEX :: A(N)
CF2PY DOUBLE COMPLEX :: B(N)
CF2PY DOUBLE COMPLEX :: C(N)
      DOUBLE COMPLEX A(*)
      DOUBLE COMPLEX B(*)
      DOUBLE COMPLEX C(*)
      INTEGER N
      DO 20 J = 1, N
         C(J) = A(J) + B(J)
 20   CONTINUE
      END

然后,可以使用以下命令编译扩展模块:

python -m numpy.f2py -c -m add add.f

函数 add.zadd 的生成签名与之前创建的签名完全相同。如果原来的源代码中已经包含了and等代替A(N),那么在源代码中放置注释行就可以得到几乎相同的界面 。唯一的区别是,这是一个可选输入,默认长度为.A(*)BCINTENT(OUT) :: CNA

过滤示例#

此示例显示了一个使用固定平均滤波器来过滤双精度浮点数二维数组的函数。从这个示例中应该可以清楚地看出使用 Fortran 索引多维数组的优点。

C
      SUBROUTINE DFILTER2D(A,B,M,N)
C
      DOUBLE PRECISION A(M,N)
      DOUBLE PRECISION B(M,N)
      INTEGER N, M
CF2PY INTENT(OUT) :: B
CF2PY INTENT(HIDE) :: N
CF2PY INTENT(HIDE) :: M
      DO 20 I = 2,M-1
         DO 40 J = 2,N-1
            B(I,J) = A(I,J) +
     &           (A(I-1,J)+A(I+1,J) +
     &           A(I,J-1)+A(I,J+1) )*0.5D0 +
     &           (A(I-1,J-1) + A(I-1,J+1) +
     &           A(I+1,J-1) + A(I+1,J+1))*0.25D0
 40      CONTINUE
 20   CONTINUE
      END

可以使用以下命令编译此代码并将其链接到名为 filter 的扩展模块中:

python -m numpy.f2py -c -m filter filter.f

这将在当前目录中生成一个扩展模块,其方法名为dfilter2d返回输入的过滤版本。

depends关键字示例#

考虑保存在文件中的以下代码myroutine.f90

subroutine s(n, m, c, x)
	implicit none
  	integer, intent(in) :: n, m
  	real(kind=8), intent(out), dimension(n,m) :: x
  	real(kind=8), intent(in) :: c(:)

	x = 0.0d0
	x(1, 1) = c(1)

end subroutine s

用 包裹起来,我们可以在 Python 中执行以下操作:python -m numpy.f2py -c myroutine.f90 -m myroutine

>>> import numpy as np
>>> import myroutine
>>> x = myroutine.s(2, 3, np.array([5, 6, 7]))
>>> x
array([[5., 0., 0.],
   [0., 0., 0.]])

现在,我们将首先为此子例程创建一个签名文件,而不是直接生成扩展模块。这是多步扩展模块生成的常见模式。在这种情况下,运行后

python -m numpy.f2py myroutine.f90 -h myroutine.pyf

生成如下签名文件:

!    -*- f90 -*-
! Note: the context of this file is case sensitive.

python module myroutine ! in 
    interface  ! in :myroutine
        subroutine s(n,m,c,x) ! in :myroutine:myroutine.f90
            integer intent(in) :: n
            integer intent(in) :: m
            real(kind=8) dimension(:),intent(in) :: c
            real(kind=8) dimension(n,m),intent(out),depend(m,n) :: x
        end subroutine s
    end interface 
end python module myroutine

! This file was auto-generated with f2py (version:1.23.0.dev0+120.g4da01f42d).
! See:
! https://web.archive.org/web/20140822061353/http://cens.ioc.ee/projects/f2py2e

现在,如果我们运行我们会看到一个错误;请注意,签名文件包含不必要的声明 。事实上,编辑上面的文件来读取python -m numpy.f2py -c myroutine.pyf myroutine.f90depend(m,n)x

!    -*- f90 -*-
! Note: the context of this file is case sensitive.

python module myroutine ! in 
    interface  ! in :myroutine
        subroutine s(n,m,c,x) ! in :myroutine:myroutine.f90
            integer intent(in) :: n
            integer intent(in) :: m
            real(kind=8) dimension(:),intent(in) :: c
            real(kind=8) dimension(n,m),intent(out) :: x
        end subroutine s
    end interface 
end python module myroutine

! This file was auto-generated with f2py (version:1.23.0.dev0+120.g4da01f42d).
! See:
! https://web.archive.org/web/20140822061353/http://cens.ioc.ee/projects/f2py2e

并且运行会产生正确的结果。f2py -c myroutine.pyf myroutine.f90

阅读更多