三种包装方式 - 入门#

使用 F2PY 将 Fortran 或 C 函数包装到 Python 中涉及以下步骤

创建所谓的签名文件，其中包含 Fortran 或 C 函数包装器的描述，也称为函数签名。对于 Fortran 例程，F2PY 可以通过扫描 Fortran 源代码并跟踪创建包装函数所需的所有相关信息来创建初始签名文件。
- 可以选择性地编辑 F2PY 创建的签名文件以优化包装函数，这可以使它们“更智能”和“更 Pythonic”。
F2PY 读取签名文件并写入包含 Fortran/C/Python 绑定的 Python C/API 模块。
F2PY 编译所有源文件并构建一个包含包装器的扩展模块。
- 在构建扩展模块时，F2PY 使用 meson，以前使用 numpy.distutils。有关不同的构建系统，请参阅 F2PY 和构建系统。

注意

有关迁移信息，请参阅 1 迁移到 meson。

根据您的操作系统，您可能需要单独安装 Python 开发头文件（提供 Python.h 文件）。在基于 Debian 的 Linux 发行版中，此软件包应命名为 python3-dev；在基于 Fedora 的发行版中，则为 python3-devel。对于 macOS，具体取决于 Python 的安装方式，可能有所不同。在 Windows 上，头文件通常已安装，请参阅 F2PY 和 Windows。

注意

F2PY 支持 SciPy 测试的所有操作系统，因此它们的系统依赖项面板是一个很好的参考。

根据具体情况，这些步骤可以一次性完成，也可以分步进行；在后一种情况下，一些步骤可以省略或与其他步骤合并。

下面，我们将介绍使用 F2PY 处理 Fortran 77 的三种典型方法。可以按工作量递增的顺序阅读它们，同时考虑到根据 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 -m numpy.f2py 可以看到命令行选项列表。现在，在 Python 中，可以通过 fib1.fib 访问 Fortran 子程序 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 连续且 dtype 与假定的 Fortran 类型匹配的 NumPy 数组作为输入数组参数时，其 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 非常类似于在 Fortran 中使用 FIB。但是，在 Python 中使用“原地”输出参数是不好的风格，因为 Python 中没有安全机制来防止错误的参数类型。在使用 Fortran 或 C 时，编译器会在编译过程中发现任何类型不匹配，但在 Python 中，类型必须在运行时检查。因此，在 Python 中使用“原地”输出参数可能会导致难以发现的 bug，更不用说当实现了所有必需的类型检查时，代码的可读性会降低。

虽然到目前为止讨论的将 Fortran 例程包装到 Python 中的方法非常直接，但它有几个缺点（参见上面的注释）。缺点是 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 是一个输入参数（使用 intent(in) 属性），并且返回值，即调用 Fortran 函数 FIB 后 a 的内容，应该返回给 Python（使用 intent(out) 属性）。此外，数组 a 应该使用输入参数 n 确定的大小动态创建（使用 depend(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.]

注意

现在 fib2.fib 的签名更接近 Fortran 子程序 FIB 的意图：给定数字 n，fib2.fib 返回前 n 个斐波那契数作为一个 NumPy 数组。新的 Python 签名 fib2.fib 也排除了 fib1.fib 中的意外行为。
请注意，默认情况下，使用单个 intent(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.]