使用 F2PY#

本页面包含了对 f2py 命令的所有命令行选项的参考,以及对 numpy.f2py 模块内部函数的参考.

使用 f2py 作为命令行工具#

当作为命令行工具使用时,``f2py`` 有三种主要模式,通过 -c 和 -h 开关来区分.

1. 签名文件生成#

要扫描 Fortran 源代码并生成签名文件,请使用

f2py -h <filename.pyf> <options> <fortran files>   \
  [[ only: <fortran functions>  : ]                \
    [ skip: <fortran functions>  : ]]...           \
  [<fortran files> ...]

备注

一个 Fortran 源文件可以包含许多例程,通常不需要允许所有例程从 Python 中使用.在这种情况下,可以在 only: .. : 部分指定应包装哪些例程,或在 skip: .. : 部分指定 F2PY 应忽略哪些例程.

F2PY 没有”每个文件”的 skip 或 only 列表的概念,所以如果函数列在 only 中,则不会从任何其他文件中获取其他函数.

如果 <filename.pyf> 被指定为 stdout,那么签名将被写入标准输出而不是文件.

在其他选项中（见下文）,以下选项可以在此模式中使用:

--overwrite-signature

覆盖现有的签名文件.

2. 扩展模块构造#

要构建一个扩展模块,请使用

f2py -m <modulename> <options> <fortran files>   \
  [[ only: <fortran functions>  : ]              \
    [ skip: <fortran functions>  : ]]...          \
  [<fortran files> ...]

构建的扩展模块保存为 <modulename>module.c 到当前目录.

这里 <fortran 文件> 也可能包含签名文件.在其他选项中（见下文）,以下选项可以在此模式中使用:

--debug-capi

向扩展模块添加调试钩子.使用此扩展模块时,各种关于包装器的诊断信息会写入标准输出,例如变量的值、采取的步骤等.

-include'<includefile>'

在扩展模块源代码中添加一个 CPP #include 语句.``<includefile>`` 应采用以下形式之一

"filename.ext"
<filename.ext>

include 语句正好在包装函数之前插入.此功能使得在 F2PY 生成的包装器中使用任意 C 函数（在 <includefile> 中定义）成为可能.

备注

此选项已弃用.使用 usercode 语句直接在签名文件中指定 C 代码片段.

--[no-]wrap-functions

创建 Fortran 子程序包装器以包装 Fortran 函数.``–wrap-functions`` 是默认选项,因为它确保了最大的可移植性和编译器独立性.

--[no-]freethreading-compatible

创建一个声明它是否需要GIL的模块.默认情况下,为了向后兼容,使用 --no-freethreading-compatible.在传递 --freethreading-compatible 之前,检查你正在包装的fortran代码的线程安全问题,因为 f2py 不会分析fortran代码的线程安全问题.

--include-paths "<path1>:<path2>..."

从给定的目录中搜索包含文件.

备注

路径应以正确的操作系统分隔符 pathsep 分隔,即在 Linux / MacOS 上是 :,在 Windows 上是 ;.在 CMake 中,这对应于使用 $<SEMICOLON>.

--help-link [<资源名称列表>]

列出由 numpy_distutils/system_info.py 找到的系统资源.例如,尝试 f2py --help-link lapack_opt.

3. 构建一个模块#

要构建一个扩展模块,请使用

f2py -c <options> <fortran files>       \
  [[ only: <fortran functions>  : ]     \
    [ skip: <fortran functions>  : ]]... \
  [ <fortran/c source files> ] [ <.o, .a, .so files> ]

如果 <fortran 文件> 包含一个签名文件,那么将构建一个扩展模块的源代码,所有 Fortran 和 C 源代码都会被编译,最后所有对象文件和库文件都会被链接到扩展模块 <模块名>.so ,并保存到当前目录中.

如果 <fortran 文件> 不包含签名文件,那么在继续构建扩展模块之前,会通过扫描所有 Fortran 源代码以获取例程签名来构建扩展模块.

警告

从 Python 3.12 开始,``distutils`` 已被移除.请使用环境变量或本地文件与 meson 进行交互.更多信息请参见其 FAQ.

除了下面描述的选项和其他模式描述的选项外,还可以使用以下选项.

备注

在 1.26.0 版本发生变更: 现在有两种不同的构建后端可以使用,``distutils`` 和 meson.强烈建议用户切换到 meson,因为它是 Python 3.12 以上的默认选项.

常见的构建标志:

--backend <backend_type>

指定编译过程的构建后端.支持的后端有 meson 和 distutils.如果未指定,默认为 distutils.在 Python 3.12 或更高版本上,默认值为 meson.

--f77flags=<string>

指定 F77 编译器标志

--f90flags=<string>

指定 F90 编译器标志

--debug

使用调试信息进行编译

-l<libname>

在链接时使用库 <libname>.

-D<macro>[=<defn=1>]

将宏 <macro> 定义为 <defn>.

-U<macro>

定义宏 <macro>

-I<dir>

将目录 <dir> 附加到搜索包含文件的目录列表中.

-L<dir>

将目录 <dir> 添加到搜索 -l 的目录列表中.

meson 特定的标志是:

--dep <dependency> 仅限 meson

为模块指定一个 meson 依赖.这可以多次传递以指定多个依赖项.依赖项存储在一个列表中以供进一步处理.示例:--dep lapack --dep scalapack 这将识别 “lapack” 和 “scalapack” 作为依赖项,并从 argv 中移除它们,留下一个包含 [“lapack”, “scalapack”] 的依赖项列表.

较旧的 distutils 标志是:

--help-fcompiler 没有 meson

列出可用的 Fortran 编译器.

--fcompiler=<Vendor> no meson

通过供应商指定 Fortran 编译器类型.

--f77exec=<path> no meson

指定一个 F77 编译器的路径

--f90exec=<path> no meson

指定一个 F90 编译器的路径

--opt=<string> 没有 meson

指定优化标志

--arch=<string> 不使用 meson

指定特定于架构的优化标志

--noopt 没有 meson

编译时不使用优化标志

--noarch 没有 meson

在不使用架构相关的优化标志的情况下编译

link-<resource> 没有 meson

使用 numpy_distutils/system_info.py 定义的 <resource> 链接扩展模块.例如,要链接优化的 LAPACK 库（MacOSX 上的 vecLib,其他地方的 ATLAS）,使用 --link-lapack_opt.另请参见 --help-link 开关.

备注

f2py -c 选项必须应用于现有的 .pyf 文件（加上源文件/对象文件/库文件）,或者必须指定 -m <模块名> 选项（加上源文件/对象文件/库文件）.请使用以下选项之一:

f2py -c -m fib1 fib1.f

或

f2py -m fib1 fib1.f -h fib1.pyf
f2py -c fib1.pyf fib1.f

更多信息,请参阅 构建 C 和 C++ 扩展 Python 文档以获取详细信息.

在构建扩展模块时,可能需要以下宏的组合以用于非gcc的Fortran编译器:

-DPREPEND_FORTRAN
-DNO_APPEND_FORTRAN
-DUPPERCASE_FORTRAN

要测试 F2PY 生成的接口的性能,请使用 -DF2PY_REPORT_ATEXIT.然后在 Python 退出时会打印出各种时间报告.此功能可能不适用于所有平台,目前仅支持 Linux.

要查看 F2PY 生成的接口是否对数组参数执行复制操作,请使用 -DF2PY_REPORT_ON_ARRAY_COPY=<int>.当数组参数的大小大于 <int> 时,有关复制的信息将发送到 stderr.

其他选项#

-m <modulename>

扩展模块的名称.默认是 untitled.

警告

如果使用签名文件（*.pyf）,请不要使用此选项.

在 1.26.3 版本发生变更: 如果提供了 pyf 文件,将忽略 -m.

--[no-]lower

不要在 <fortran 文件> 中降低大小写.默认情况下,使用 -h 开关时假设 --lower,不使用 -h 开关时假设 --no-lower.

-include<header>

在C包装器中写入额外的头文件,可以多次传递,每次生成 #include <header>.请注意,这应该用单引号传递且不带空格,例如 '-include<stdbool.h>'

--build-dir <dirname>

所有由 F2PY 生成的文件都创建在 <dirname> 中.默认是 tempfile.mkdtemp().

--f2cmap <filename>

从给定文件加载 Fortran-to-C KIND 规范.

--quiet

安静运行.

--verbose

以额外的详细程度运行.

--skip-empty-wrappers

除非输入要求,否则不要生成包装文件.这是一个向后兼容标志,用于恢复1.22.4之前的行为.

-v

打印 F2PY 版本并退出.

执行 f2py 没有任何选项以获取最新的可用选项列表.

Python 模块 numpy.f2py#

警告

在 2.0.0 版本发生变更: 曾经有一个 f2py.compile 函数,该函数已被移除,用户可以通过 subprocess.run 手动包装 python -m numpy.f2py,并根据需要设置环境变量以与 meson 交互.

当使用 numpy.f2py 作为模块时,可以调用以下函数.

Fortran 到 Python 接口生成器.

版权所有 1999 – 2011 Pearu Peterson 保留所有权利.版权所有 2011 – 至今 NumPy 开发者.根据 NumPy 许可证的条款,授予使用、修改和分发此软件的权限.

不提供任何明示或暗示的保证.使用风险自负.

numpy.f2py.get_include()[源代码][源代码]#

返回包含 fortranobject.c 和 .h 文件的目录.

备注

当直接从 .f 和/或 .pyf 文件一次性构建扩展时,使用 numpy.distutils 时不需要此功能.

使用 f2py 生成的代码构建的 Python 扩展模块需要将 fortranobject.c 作为源文件,并包含 fortranobject.h 头文件.此函数可用于获取包含这两个文件的目录.

返回:
include_pathstr

包含 fortranobject.c 和 fortranobject.h 的目录的绝对路径.

参见

numpy.get_include

返回 numpy 包含目录的函数

备注

在 1.21.1 版本加入.

除非你使用的构建系统对 f2py 有特定的支持,否则使用 .pyf 签名文件构建 Python 扩展是一个两步过程.对于模块 mymod:

  • 步骤 1:运行 python -m numpy.f2py mymod.pyf --quiet.这将生成 mymodmodule.c 和（如果需要） mymod-f2pywrappers.f 文件在 mymod.pyf 旁边.

  • 步骤2:构建您的Python扩展模块.这需要以下源文件:

    • mymodmodule.c

    • mymod-f2pywrappers.f （如果它在第1步中生成）

    • fortranobject.c

numpy.f2py.run_main(comline_list)[源代码][源代码]#

相当于运行:

f2py <args>

其中 <args>=string.join(<list>,' '),但在 Python 中.除非使用 -h,否则此函数返回一个包含有关生成的模块及其对源文件依赖关系的字典.

你不能使用此函数构建扩展模块,即不允许使用 -c.请改用 compile 命令.

示例

命令 f2py -m scalar scalar.f 可以如下从 Python 执行.

>>> import numpy.f2py
>>> r = numpy.f2py.run_main(['-m','scalar','doc/source/f2py/scalar.f'])
Reading fortran codes...
        Reading file 'doc/source/f2py/scalar.f' (format:fix,strict)
Post-processing...
        Block: scalar
                        Block: FOO
Building modules...
        Building module "scalar"...
        Wrote C/API module "scalar" to file "./scalarmodule.c"
>>> print(r)
{'scalar': {'h': ['/home/users/pearu/src_cvs/f2py/src/fortranobject.h'],
	 'csrc': ['./scalarmodule.c', 
                  '/home/users/pearu/src_cvs/f2py/src/fortranobject.c']}}

自动扩展模块生成#

如果你想分发你的 f2py 扩展模块,那么你只需要包含 .pyf 文件和 Fortran 代码.NumPy 中的 distutils 扩展允许你完全根据这个接口文件定义一个扩展模块.一个有效的 setup.py 文件允许分发 add.f 模块（作为包 f2py_examples 的一部分,因此它将被加载为 f2py_examples.add）是:

def configuration(parent_package='', top_path=None)
    from numpy.distutils.misc_util import Configuration
    config = Configuration('f2py_examples',parent_package, top_path)
    config.add_extension('add', sources=['add.pyf','add.f'])
    return config

if __name__ == '__main__':
    from numpy.distutils.core import setup
    setup(**configuration(top_path='').todict())

使用以下方法安装新包非常简单:

pip install .

假设你有适当的权限来写入你正在使用的Python版本的站点包主目录.为了让生成的包工作,你需要创建一个名为 __init__.py 的文件（在与 add.pyf 相同的目录中）.注意扩展模块完全根据 add.pyf 和 add.f 文件定义.将 .pyf 文件转换为 .c 文件的处理由 numpy.distutils 完成.

On this page