Использование F2PY#

Эта страница содержит справочник по всем параметрам командной строки для f2py команда, а также ссылка на внутренние функции numpy.f2py модуль.

Используя `f2py` как инструмент командной строки#

При использовании в качестве инструмента командной строки, f2py имеет три основных режима, различаемых по использованию -c и -h переключает.

1. Генерация файла сигнатур#

Для сканирования исходных кодов Fortran и создания файла сигнатур используйте

f2py -h    files>   \
  [[ only:  functions>  : ]                \
    [ skip:  functions>  : ]]...           \
  [ files> ...]

Примечание

Исходный файл Fortran может содержать множество подпрограмм, и часто нет необходимости разрешать использование всех подпрограмм из Python. В таких случаях либо укажите, какие подпрограммы должны быть обернуты (в only: .. : часть) или какие подпрограммы F2PY должен игнорировать (в skip: .. : часть).

F2PY не имеет концепции «на файл» skip или only список, поэтому если функции перечислены в only, никакие другие функции не будут взяты из других файлов.

Если указывается как stdout, тогда сигнатуры записываются в стандартный вывод вместо файла.

Среди других опций (см. ниже) в этом режиме можно использовать следующие:

--overwrite-signature: Перезаписывает существующий файл сигнатуры.

2. Построение расширяющего модуля#

Для создания модуля расширения используйте

f2py -m    files>   \
  [[ only:  functions>  : ]              \
    [ skip:  functions>  : ]]...          \
  [ files> ...]

Созданный модуль расширения сохраняется как module.c в текущий каталог.

Здесь files> также может содержать файлы подписей. Среди других опций (см. ниже) в этом режиме можно использовать следующие опции:

--debug-capi

Добавляет отладочные хуки в модуль расширения. При использовании этого модуля расширения различная диагностическая информация об обёртке записывается в стандартный вывод, например, значения переменных, выполненные шаги и т.д.

-include''

Добавить CPP #include оператор в исходный код модуля расширения. должен быть указан в одной из следующих форм

"filename.ext"
<filename.ext>

Оператор include вставляется непосредственно перед функциями-обёртками. Эта функция позволяет использовать произвольные C-функции (определённые в ) в обёртках, сгенерированных F2PY.

Примечание

Эта опция устарела. Используйте usercode утверждение для указания фрагментов кода C непосредственно в файлах сигнатур.

--[no-]wrap-functions

Создание обёрток подпрограмм Fortran для функций Fortran. --wrap-functions является значением по умолчанию, потому что это обеспечивает максимальную переносимость и независимость от компилятора.

--[no-]freethreading-compatible

Создайте модуль, который объявляет, требует он GIL или нет. По умолчанию --no-freethreading-compatible для обратной совместимости. Проверьте код Fortran, который вы оборачиваете, на проблемы потокобезопасности перед передачей --freethreading-compatible, как f2py не анализирует код Fortran на проблемы с потокобезопасностью.

--include-paths ":..."

Поиск включаемых файлов из заданных каталогов.

Примечание

Пути должны разделяться корректным разделителем операционной системы pathsep, то есть : на Linux / MacOS и ; в Windows. В CMake это соответствует использованию $.

--help-link [ of resources names>]

Список системных ресурсов, найденных numpy_distutils/system_info.py. Например, попробуйте f2py --help-link lapack_opt.

3. Построение модуля#

Для построения модуля расширения используйте

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

Если files> содержит файл сигнатуры, то создаётся исходный код для модуля расширения, все исходные коды Fortran и C компилируются, и, наконец, все объектные и библиотечные файлы связываются с модулем расширения .so который сохраняется в текущем каталоге.

Если files> не содержит файл сигнатуры, то модуль расширения строится путём сканирования всех исходных кодов Fortran на наличие сигнатур подпрограмм перед сборкой модуля расширения.

Предупреждение

Начиная с Python 3.12, distutils был удален. Используйте переменные окружения или нативные файлы для взаимодействия с meson вместо. См. его Часто задаваемые вопросы для получения дополнительной информации.

Среди других опций (см. ниже) и опций, описанных для предыдущих режимов, можно использовать следующие.

Примечание

Изменено в версии 1.26.0: Теперь доступны две отдельные системы сборки, которые можно использовать, distutils и meson. Пользователи сильно рекомендуется перейти на meson поскольку это значение по умолчанию выше Python 3.12.

Общие флаги сборки:

--backend: Укажите бэкенд сборки для процесса компиляции. Поддерживаемые бэкенды: meson и distutils. Если не указано, по умолчанию distutils. В Python 3.12 или выше по умолчанию используется meson.
--f77flags=: Укажите флаги компилятора F77
--f90flags=: Указать флаги компилятора F90
--debug: Компиляция с отладочной информацией
-l: Используйте библиотеку при связывании.
-D[=]: Определить макрос как .
-U: Определить макрос
-I: Добавить каталог
в список каталогов, в которых производится поиск включаемых файлов.
-L: Добавить каталог
в список директорий для поиска -l.

The meson специфичные флаги:

--dep только meson: Укажите зависимость meson для модуля. Это может быть передано несколько раз для нескольких зависимостей. Зависимости сохраняются в списке для дальнейшей обработки. Пример: --dep lapack --dep scalapack Это определит 'lapack' и 'scalapack' как зависимости и удалит их из argv, оставив список зависимостей, содержащий ['lapack', 'scalapack'].

Старый distutils флаги:

--help-fcompiler нет meson: Перечислите доступные компиляторы Fortran.
--fcompiler= нет meson: Укажите тип компилятора Fortran по производителю.
--f77exec= нет meson: Укажите путь к компилятору F77
--f90exec= нет meson: Укажите путь к компилятору F90
--opt= нет meson: Укажите флаги оптимизации
--arch= нет meson: Укажите флаги оптимизации для конкретной архитектуры
--noopt нет meson: Компиляция без флагов оптимизации
--noarch нет meson: Компилировать без флагов оптимизации, зависящих от архитектуры
link- нет meson: Свяжите модуль расширения с , как определено в numpy_distutils/system_info.pyНапример, для связи с оптимизированными библиотеками LAPACK (vecLib на MacOSX, ATLAS в других системах), используйте --link-lapack_opt. См. также --help-link переключатель.

Примечание

The 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 документация для подробностей.

При сборке расширяемого модуля может потребоваться комбинация следующих макросов для компиляторов Fortran, отличных от gcc:

-DPREPEND_FORTRAN
-DNO_APPEND_FORTRAN
-DUPPERCASE_FORTRAN

Для тестирования производительности интерфейсов, сгенерированных F2PY, используйте -DF2PY_REPORT_ATEXIT. Затем при выходе из Python выводится отчет о различных временных показателях. Эта функция может не работать на всех платформах, и в настоящее время поддерживается только Linux.

Чтобы проверить, выполняет ли интерфейс, сгенерированный F2PY, копирование аргументов массива, используйте -DF2PY_REPORT_ON_ARRAY_COPY=. Когда размер аргумента массива больше, чем , сообщение о копировании отправляется в stderr.

Другие опции#

-m: Имя модуля расширения. По умолчанию untitled.

Предупреждение

Не используйте эту опцию, если файл сигнатуры (*.pyf) используется.

Изменено в версии 1.26.3: Будет игнорировать -m если pyf файл предоставлен.

--[no-]lower: Не [снижать] регистр в files>. По умолчанию, --lower предполагается с -h переключатель, и --no-lower без -h переключатель.
-include: Записывает дополнительные заголовки в C-обёртку, может передаваться несколько раз, генерирует #include
каждый раз. Обратите внимание, что это должно передаваться в одинарных кавычках и без пробелов, например '-include'
--build-dir: Все сгенерированные F2PY файлы создаются в . По умолчанию tempfile.mkdtemp().
--f2cmap: Загрузить Fortran-to-C KIND спецификации из данного файла.
--quiet: Запускать тихо.
--verbose: Запуск с дополнительной подробностью вывода.
--skip-empty-wrappers: Не генерировать файлы-обёртки, если они не требуются входными данными. Это флаг обратной совместимости для восстановления поведения до версии 1.22.4.
-v: Вывести версию F2PY и завершить работу.

Выполнить f2py без каких-либо опций, чтобы получить актуальный список доступных опций.

Модуль Python `numpy.f2py`#

Предупреждение

Изменено в версии 2.0.0: Раньше существовал f2py.compile функция, которая была удалена, пользователи могут обернуть python -m numpy.f2py через subprocess.run вручную и установить переменные окружения для взаимодействия с meson как требуется.

При использовании numpy.f2py как модуль, следующие функции могут быть вызваны.

Fortran to Python Interface Generator.

Авторские права 1999 – 2011 Pearu Peterson, все права защищены. Авторские права 2011 – настоящее время Разработчики NumPy. Разрешение на использование, изменение и распространение этого программного обеспечения предоставляется на условиях лицензии NumPy.

НИКАКИХ ГАРАНТИЙ НЕ ПРЕДОСТАВЛЯЕТСЯ. ИСПОЛЬЗУЙТЕ НА СВОЙ СТРАХ И РИСК.

numpy.f2py.get_include()[источник]#

Возвращает каталог, содержащий fortranobject.c и .h файлы.

Примечание

Эта функция не требуется при сборке расширения с numpy.distutils непосредственно из .f и/или .pyf файлы за один раз.

Модули расширения Python, собранные с кодом, сгенерированным f2py, должны использовать fortranobject.c как исходный файл, и включить fortranobject.h заголовок. Эта функция может использоваться для получения каталога, содержащего оба этих файла.

Возвращает:

include_pathstr: Абсолютный путь к каталогу, содержащему fortranobject.c и fortranobject.h.

Смотрите также

numpy.get_include: функция, возвращающая директорию include numpy

Примечания

Новое в версии 1.21.1.

Если система сборки, которую вы используете, не имеет специальной поддержки f2py, сборка расширения Python с использованием .pyf файл сигнатуры — это двухэтапный процесс. Для модуля 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>

где =string.join(,' '), но на 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. Расширения distutils в NumPy позволяют определить модуль расширения полностью в терминах этого файла интерфейса. Действительный 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 .

при условии, что у вас есть соответствующие разрешения на запись в основной каталог site-packages для используемой версии Python. Чтобы полученный пакет работал, вам нужно создать файл с именем __init__.py (в той же директории, что и add.pyf). Обратите внимание, что модуль расширения полностью определен в терминах add.pyf и add.f файлы. Преобразование файла .pyf в файл .c обрабатывается numpy.distutils.

Сборка с помощью Meson (Примеры)#

Использование f2py с Meson#

Meson — современная система сборки, рекомендуемая для сборки модулей расширения Python, особенно начиная с Python 3.12 и NumPy 2.x. Meson предоставляет надежный и поддерживаемый способ сборки расширений Fortran с f2py.

Для сборки Fortran расширения с использованием f2py и Meson, вы можете использовать custom_target для вызова f2py и генерации модуля расширения. Следующий минимальный пример демонстрирует, как это сделать:

Этот пример показывает, как построить add расширение из add.f и add.pyf файлы, описанные в Примеры F2PY (обратите внимание, что не всегда нужен .pyf файл: во многих случаях f2py может самостоятельно определить аннотации).

Структура проекта:

f2py_examples/
meson.build add.f add.pyf (опционально) __init__.py (может быть пустым)

Пример meson.build:

project('f2py_examples', 'fortran')

py = import('python').find_installation()

# List your Fortran source files
sources = files('add.pyf', 'add.f')

# Build the extension by invoking f2py via a custom target
add_mod = custom_target(
  'add_extension',
  input: sources,
  output: ['add' + py.extension_suffix()],
  command: [
    py.full_path(), '-m', 'numpy.f2py',
    '-c', 'add.pyf', 'add.f',
    '-m', 'add'
  ],
  build_by_default: true
)

# Install into site-packages under the f2py_examples package
install_subdir('.', install_dir: join_paths(py.site_packages_dir(), 'f2py_examples'),
               strip_directory: false,
               exclude_files: ['meson.build'])

# Also install the built extension (place it beside __init__.py)
install_data(add_mod, install_dir: join_paths(py.site_packages_dir(), 'f2py_examples'))

Для получения более подробной информации и расширенного использования см. руководство по сборке Meson в пользовательской документации или обратитесь к файлам сборки Meson SciPy для реальных примеров: scipy/scipy

Использование F2PY#

Используя f2py как инструмент командной строки#

1. Генерация файла сигнатур#

2. Построение расширяющего модуля#

3. Построение модуля#

Другие опции#

Модуль Python numpy.f2py#

Автоматическая генерация модулей расширения#

Сборка с помощью Meson (Примеры)#

Использование f2py с Meson#

Используя `f2py` как инструмент командной строки#

Модуль Python `numpy.f2py`#