三种包装方式 - 入门#

使用 F2PY 将 Fortran 或 C 函数包装到 Python 包括以下步骤：

  • 创建所谓的签名文件，其中包含 Fortran 或 C 函数包装器的描述，也称为函数签名。对于 Fortran 例程，F2PY 可以通过扫描 Fortran 源代码并跟踪创建包装函数所需的所有相关信息来创建初始签名文件。

    • 或者，可以编辑 F2PY 创建的签名文件来优化包装函数，这可以使它们“更智能”、更“Pythonic”。

  • F2PY 读取签名文件并写入包含 Fortran/C/Python 绑定的 Python C/API 模块。

  • F2PY 编译所有源代码并构建包含包装器的扩展模块。

    • 在构建扩展模块时，F2PY 使用numpy_distutils支持多种 Fortran 77/90/95 编译器，包括 Gnu、Intel、Sun Fortran、SGI MIPSpro、Absoft、NAG、Compaq 等。对于不同的构建系统，请参阅F2PY 和构建系统。

    • 根据您的操作系统，您可能需要单独安装 Python 开发标头（提供文件Python.h）。在基于 Debian 的 Linux 发行版中，该软件包应称为python3-dev，在基于 Fedora 的发行版中则为python3-devel。对于 macOS，根据 Python 的安装方式，您的情况可能会有所不同。在 Windows 中，标头通常已安装。

根据具体情况，这些步骤可以通过单个复合命令或逐步执行；在这种情况下，某些步骤可以省略或与其他步骤组合。

下面，我们描述使用 F2PY 的三种典型方法。这些可以按递增的顺序阅读，但也可以根据 Fortran 代码是否可以自由修改来满足不同的访问级别。

以下示例 Fortran 77 代码将用于说明，将其另存为fib1.f：

C FILE: FIB1.F
      SUBROUTINE FIB(A,N)
C
C     CALCULATE FIRST N FIBONACCI NUMBERS
C
      INTEGER N
      REAL*8 A(N)
      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
      END
C END FILE FIB1.F

笔记

F2PY 解析 Fortran/C 签名以构建与 Python 一起使用的包装函数。但是，它不是编译器，不会检查源代码中的其他错误，也不会实现整个语言标准。某些错误可能会默默地传递（或作为警告），需要由用户验证。

快速方法#

包装 Fortran 子例程FIB以便在 Python 中使用的最快方法是运行

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

或者，如果f2py命令行工具可用，

f2py -c fib1.f -m fib1

笔记

由于该f2py命令可能并非在所有系统中都可用，特别是在 Windows 上，因此我们将在本指南中使用该命令。python -m numpy.f2py

此命令编译并包装fib1.f( ) 以在当前目录中-c创建扩展模块fib1.so( )。-m通过执行可以看到命令行选项列表。现在，在 Python 中，可以通过以下方式访问Fortran 子例程：python -m numpy.f2pyFIBfib1.fib

>>> import numpy as np
>>> import fib1
>>> print(fib1.fib.__doc__)
fib(a,[n])

Wrapper for ``fib``.

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

Other Parameters
----------------
n : input int, optional
    Default: len(a)

>>> a = np.zeros(8, 'd')
>>> fib1.fib(a)
>>> print(a)
[  0.   1.   1.   2.   3.   5.   8.  13.]

笔记

  • 请注意，F2PY 识别出第二个参数n是第一个数组参数的维度a。由于默认情况下所有参数都是仅输入参数，因此 F2PY 得出结论n可以是可选的默认值len(a)。

  • 可以对可选值使用不同的值n：

    >>> a1 = np.zeros(8, 'd')
>>> fib1.fib(a1, 6)
>>> print(a1)
[ 0.  1.  1.  2.  3.  5.  0.  0.]

    但当它与输入数组不兼容时会引发异常a：

    >>> fib1.fib(a, 10)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
fib.error: (len(a)>=n) failed for 1st keyword n: fib:n=10
>>>

    F2PY 在相关参数之间实现基本的兼容性检查，以避免意外崩溃。

  • 当Fortran 连续且具有与假定的 Fortran 类型相对应的NumPy 数组dtype用作输入数组参数时，其 C 指针将直接传递给 Fortran。

    否则，F2PY 制作输入数组的连续副本（使用正确的dtype），并将副本的 C 指针传递给 Fortran 子例程。因此，对输入数组（的副本）的任何可能的更改都不会影响原始参数，如下所示：

    >>> a = np.ones(8, 'i')
>>> fib1.fib(a)
>>> print(a)
[1 1 1 1 1 1 1 1]

    显然，这是出乎意料的，因为 Fortran 通常通过引用传递。上面的例子dtype=float被认为是偶然的。

    F2PY 提供了一个intent(inplace)属性，可以修改输入数组的属性，以便 Fortran 例程所做的任何更改都将反映在输入参数中。例如，如果指定 指令（有关详细信息，请参阅属性），则上面的示例将显示为：intent(inplace) a

    >>> a = np.ones(8, 'i')
>>> fib1.fib(a)
>>> print(a)
[  0.   1.   1.   2.   3.   5.   8.  13.]

    但是，将 Fortran 子例程所做的更改传播到 Python 的推荐方法是使用该intent(out)属性。这种方法更有效，也更清洁。

  • Python 中的用法fib1.fib与FIBFortran 中的用法非常相似。然而，在 Python 中使用原位输出参数的方式很糟糕，因为 Python 中没有安全机制来防止错误的参数类型。使用 Fortran 或 C 时，编译器会在编译过程中发现任何类型不匹配，但在 Python 中，必须在运行时检查类型。因此，在 Python 中使用原位输出参数可能会导致难以发现错误，更不用说当实现所有必需的类型检查时代码的可读性会降低。

尽管到目前为止讨论的为 Python 封装 Fortran 例程的方法非常简单，但它有几个缺点（请参阅上面的评论）。缺点是F2PY无法确定论点的实际意图；也就是说，区分输入和输出参数存在歧义。因此，F2PY 默认情况下假定所有参数都是输入参数。

有一些方法（见下文）可以通过“教导”F2PY 关于函数参数的真实意图来消除这种歧义，然后 F2PY 就能够为 Fortran 函数生成更明确、更易于使用且不易出错的包装器。

聪明的方法#

如果我们想更好地控制 F2PY 如何处理 Fortran 代码的接口，我们可以一一应用包装步骤。

  • 首先，我们通过运行以下命令创建一个签名文件fib1.f：

    python -m numpy.f2py fib1.f -m fib2 -h fib1.pyf

    签名文件保存到fib1.pyf（见-h标志），其内容如下所示。

    !    -*- f90 -*-
python module fib2 ! in 
    interface  ! in :fib2
        subroutine fib(a,n) ! in :fib2:fib1.f
            real*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 file was auto-generated with f2py (version:2.28.198-1366).
! See http://cens.ioc.ee/projects/f2py2e/

  • 接下来，我们将教导 F2PY 参数n是输入参数（使用 属性），并且结果（ 即调用 Fortran 函数 后intent(in)的内容）应该返回到 Python（使用属性）。此外，应该使用输入参数确定的大小动态创建数组 （使用属性来指示这种依赖关系）。aFIBintent(out)andepend(n)

    fib1.pyf适当修改后的版本（另存为 ）内容fib2.pyf如下：

    !    -*- 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

  • 最后，我们通过运行以下命令来构建扩展模块numpy.distutils：

    python -m numpy.f2py -c fib2.pyf fib1.f

在Python中：

>>> import fib2
>>> print(fib2.fib.__doc__)
a = fib(n)

Wrapper for ``fib``.

Parameters
----------
n : input int

Returns
-------
a : rank-1 array('d') with bounds (n)

>>> print(fib2.fib(8))
[  0.   1.   1.   2.   3.   5.   8.  13.]

笔记

  • now的签名fib2.fib更符合 Fortran 子例程的意图FIB：给定 number n，以 NumPy 数组的形式fib2.fib 返回第一个斐波那契数。n新的 Python 签名fib2.fib还排除了 fib1.fib.

  • 请注意，默认情况下，使用 singleintent(out)也意味着 intent(hide).具有intent(hide)指定属性的参数不会列在包装函数的参数列表中。

详细信息请参见签名文件。

快速而聪明的方法#

如上所述，包装 Fortran 函数的“智能方式”适用于包装（例如第三方）Fortran 代码，对于这些代码，不需要甚至不可能对其源代码进行修改。

但是，如果可以接受编辑 Fortran 代码，则在大多数情况下可以跳过中间签名文件的生成。可以使用 F2PY 指令将 F2PY 特定属性直接插入 Fortran 源代码中。 F2PY 指令由特殊注释行（例如以 Cf2py或开头!f2py）组成，这些注释行会被 Fortran 编译器忽略，但会被 F2PY 解释为普通行。

考虑使用 F2PY 指令对先前 Fortran 代码进行修改的版本，另存为fib3.f：

C FILE: FIB3.F
      SUBROUTINE FIB(A,N)
C
C     CALCULATE FIRST N FIBONACCI NUMBERS
C
      INTEGER N
      REAL*8 A(N)
Cf2py intent(in) n
Cf2py intent(out) a
Cf2py 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
      END
C END FILE FIB3.F

现在可以通过一个命令来构建扩展模块：

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

请注意，生成的包装器FIB与前一种情况一样“智能”（明确）：

>>> import fib3
>>> print(fib3.fib.__doc__)
a = fib(n)

Wrapper for ``fib``.

Parameters
----------
n : input int

Returns
-------
a : rank-1 array('d') with bounds (n)

>>> print(fib3.fib(8))
[  0.   1.   1.   2.   3.   5.   8.  13.]