Файл подписи

Блок модуля Python

Файл подписи может содержать один (рекомендуемый) или более python module блоков. Блок python module описывает содержимое модуля расширения Python/C <modulename>module.c, который генерирует F2PY.

Блок python module имеет следующий структуру:

python module <modulename>
  [<usercode statement>]...
  [
  interface
    <usercode statement>
    <Fortran block data signatures>
    <Fortran/C routine signatures>
  end [interface]
  ]...
  [
  interface
    module <F90 modulename>
      [<F90 module data type declarations>]
      [<F90 module routine signatures>]
    end [module [<F90 modulename>]]
  end [interface]
  ]...
end [python module [<modulename>]]

Здесь квадратные скобки [] обозначают необязательную секцию, точки ... указывают одну или несколько предыдущих секций. Таким образом, []... следует понимать как ноль или более предыдущих секций.

Подписи процедур Fortran/C

Подпись процедуры Fortran имеет следующую структуру:

[<typespec>] function | subroutine <routine name> \
              [ ( [<arguments>] ) ] [ result ( <entityname> ) ]
  [<argument/variable type declarations>]
  [<argument/variable attribute statements>]
  [<use statements>]
  [<common block statements>]
  [<other statements>]
end [ function | subroutine [<routine name>] ]

Из подписи процедуры Fortran F2PY генерирует функцию расширения Python/C, которая имеет следующую подпись:

def <routine name>(<required arguments>[,<optional arguments>]):
     ...
     return <return variables>

Подпись блока данных Fortran имеет следующую структуру:

block data [ <block data name> ]
  [<variable type declarations>]
  [<variable attribute statements>]
  [<use statements>]
  [<common block statements>]
  [<include statements>]
end [ block data [<block data name>] ]

Объявления типов

Определение части <argument/variable type declaration>:

<typespec> [ [<attrspec>] :: ] <entitydecl>

где

<typespec> := byte | character [<charselector>]
           | complex [<kindselector>] | real [<kindselector>]
           | double complex | double precision
           | integer [<kindselector>] | logical [<kindselector>]

<charselector> := * <charlen>
               | ( [len=] <len> [ , [kind=] <kind>] )
               | ( kind= <kind> [ , len= <len> ] )
<kindselector> := * <intlen> | ( [kind=] <kind> )

<entitydecl> := <name> [ [ * <charlen> ] [ ( <arrayspec> ) ]
                      | [ ( <arrayspec> ) ] * <charlen> ]
                     | [ / <init_expr> / | = <init_expr> ] \
                       [ , <entitydecl> ]

и

• <attrspec> — это список атрибутов, разделённых запятыми;
• <arrayspec> — это список границ размерностей, разделённых запятыми;
• <init_expr> — это C-выражение;
• <intlen> может быть отрицательным целым числом для integer спецификаций типов. В таких случаях integer*<negintlen> представляет собой беззнаковые целые числа C;

Если у аргумента нет <argument type declaration>, его тип определяется по применению правил implicit к его имени.

Операторы

Атрибуты

Следующие атрибуты могут быть использованы F2PY.

optional

Соответствующий аргумент перемещается в конец списка <optional arguments>. Значение по умолчанию для необязательного аргумента можно указать через <init_expr> (см. entitydecl определение)

Примечание

• Значение по умолчанию должно быть задано как допустимое выражение языка C.
• Всякий раз, когда используется <init_expr>, атрибут optional автоматически устанавливается F2PY.
• Для необязательного массива-аргумента все его размерности должны быть ограничены.

required

Соответствующий аргумент с этим атрибутом считается обязательным. Это значение по умолчанию. required следует указывать только в случае необходимости отключения автоматической optional установки при использовании <init_expr>.

Если в качестве обязательного аргумента используется объект Python None, аргумент обрабатывается как необязательный. То есть в случае с массивами-аргументами память выделяется. Если задан <init_expr>, то выполняется соответствующая инициализация.

dimension(<arrayspec>)

Соответствующая переменная рассматривается как массив с размерностями, заданными в <arrayspec>.

intent(<intentspec>)

Это указывает «намерение» соответствующего аргумента. <intentspec> — это список ключей, разделенных запятыми:

• in

  Соответствующий аргумент считается только входным. Это означает, что значение аргумента передается в функцию Fortran/C, и ожидается, что функция не изменит значение этого аргумента.

• inout

  Соответствующий аргумент помечен как вход/выход или как in situ аргумент вывода. Аргументы intent(inout) могут быть только непрерывными массивами NumPy (в смысле Fortran или C) с правильным типом и размером. Последнее совпадает с концепцией непрерывности по умолчанию, используемой в NumPy, и эффективно только если используется intent(c). F2PY по умолчанию предполагает непрерывные аргументы Fortran.

  Примечание

  Использование intent(inout) обычно не рекомендуется, так как это может привести к непредсказуемым результатам. Например, скалярные аргументы, использующие intent(inout) предполагаются объектами массива, чтобы изменения in situ были эффективными. Используйте intent(in,out) вместо этого.

  См. также атрибут intent(inplace).

• inplace

  Соответствующий аргумент считается аргументом вход/выход или in situ аргументом вывода. Аргументы intent(inplace) должны быть массивами NumPy соответствующего размера. Если тип массива не «правильный» или массив не непрерывный, то массив будет изменён на месте для исправления типа и непрерывности.

  Примечание

  Использование intent(inplace) также не рекомендуется.

  Например, когда из аргумента intent(inplace) были взяты срезы, после изменений на месте указатели данных для срезов могут указывать на незарезервированную область памяти.

• out

  Соответствующий аргумент считается переменной возврата. Он добавляется в список <returned variables> . Использование intent(out) автоматически устанавливает intent(hide), если не заданы intent(in) или intent(inout).

  По умолчанию возвращаемые многомерные массивы являются непрерывными в смысле Fortran. Если используется атрибут intent(c), то возвращаемые многомерные массивы являются непрерывными в смысле C.

• hide

  Соответствующий аргумент удаляется из списка обязательных или необязательных аргументов. Обычно intent(hide) используется с intent(out) или когда значение аргумента полностью определяется <init_expr> , как в следующем примере:

  integer intent(hide),depend(a) :: n = len(a)
  real intent(in),dimension(n) :: a
  

• c

  Соответствующий аргумент обрабатывается как скалярный или массивный аргумент C. В случае скалярного аргумента его значение передается в функцию C как скалярный аргумент C (напомню, что скалярные аргументы Fortran фактически являются указателями на аргументы C). Для аргументов-массивов предполагается, что функция-обертка обрабатывает многомерные массивы как непрерывные массивы C.

  Для одномерных массивов нет необходимости использовать intent(c), независимо от того, находится ли обернутая функция в Fortran или C. Это связано с тем, что понятия непрерывности Fortran и C совпадают в одномерных случаях.

  Если intent(c) используется как оператор, но без списка сущностей, то F2PY добавляет атрибут intent(c) ко всем аргументам.

  Также при обертывании функций C необходимо использовать атрибут intent(c) для <routine name> для отключения специфичных для Fortran F_FUNC(..,..) макросов.

• cache

  Соответствующий аргумент рассматривается как мусорная память. Проверки непрерывности Fortran и C не выполняются. Использование intent(cache) имеет смысл только для аргументов-массивов, также в сочетании с атрибутами intent(hide) или optional.

• copy

  Гарантирует, что исходное содержимое аргумента intent(in) сохраняется. Обычно используется с атрибутом intent(in,out) . F2PY создаёт необязательный аргумент overwrite_<argument name> со значением по умолчанию 0.

• overwrite

  Это указывает, что исходное содержимое аргумента intent(in) может быть изменено функцией Fortran/C. F2PY создаёт необязательный аргумент overwrite_<argument name> со значением по умолчанию 1.

• out=<new name>

  Заменяет возвращаемое имя на <new name> в строке __doc__ функции-обертки.

• callback

  Создает внешнюю функцию, подходящую для вызова функций Python из Fortran. intent(callback) должно быть указано перед соответствующим оператором external . Если 'аргумент' не содержится в списке аргументов, он будет добавлен в оболочку Python, но только путем инициализации внешней функции.

  Примечание

  Используйте intent(callback) в ситуациях, когда код Fortran/C предполагает, что пользователь реализовал функцию с заданным прототипом и связал её с исполняемым файлом. Не используйте intent(callback) , если функция появляется в списке аргументов Fortran-подпрограммы.

  При указанных атрибутах intent(hide) или optional и использовании функции-обертки без указания аргумента обратного вызова в списке аргументов; функция обратного вызова предполагается в пространстве имен сгенерированного F2PY модуля расширения, где она может быть установлена в качестве атрибута модуля пользователем.

• aux

  Определяет вспомогательную переменную C в сгенерированной F2PY функции-обертки. Полезно для сохранения значений параметров, чтобы к ним можно было обратиться в выражениях инициализации других переменных.

  Примечание

  intent(aux) молчаливо подразумевает intent(c).

Применяются следующие правила:

• Если ни один из intent(in | inout | out | hide) не указан, предполагается intent(in).

  • intent(in,inout) равно intent(in);
  • intent(in,hide) или intent(inout,hide) равно intent(hide);
  • intent(out) равно intent(out,hide) , если не указаны intent(in) или intent(inout).

• Если используется intent(copy) или intent(overwrite), то вводится дополнительный необязательный аргумент с именем overwrite_<argument name> и значением по умолчанию 0 или 1 соответственно.

  • intent(inout,inplace) равно intent(inplace);
  • intent(in,inplace) равно intent(inplace);
  • intent(hide) отключает optional и required.

check([<C-booleanexpr>])

Выполняет проверку согласованности аргументов, вычисляя <C-booleanexpr>; если <C-booleanexpr> возвращает 0, возникает исключение.

Примечание

Если check(..) не используется, F2PY автоматически генерирует несколько стандартных проверок (например, в случае аргумента-массива проверяется правильная форма и размер). Используйте check() для отключения проверок, сгенерированных F2PY.

depend([<names>])

Объявляет, что соответствующий аргумент зависит от значений переменных в списке <names>. Например, <init_expr> может использовать значения других аргументов. Используя информацию, предоставленную атрибутами depend(..), F2PY гарантирует, что аргументы будут инициализированы в правильном порядке. Если атрибут depend(..) не используется, F2PY автоматически определяет зависимости. Используйте depend() для отключения зависимостей, сгенерированных F2PY.

При редактировании зависимостей, первоначально сгенерированных F2PY, будьте осторожны, чтобы не нарушить зависимости других соответствующих переменных. Ещё одна вещь, на которую стоит обратить внимание, — это циклические зависимости. F2PY может обнаружить циклические зависимости при построении оберток и сообщает об этом, если таковые обнаружены.

allocatable

Соответствующая переменная является массивом Fortran 90, выделенным в данных модуля Fortran 90.

external

Соответствующий аргумент — функция, предоставляемая пользователем. Подпись этой обратной функции может быть определена

• в блоке модуля __user__,
• или демонстративным (или реальным, если файл подписи — реальный код Fortran) вызовом в блоке <other statements>.

Например, F2PY генерирует из:

external cb_sub, cb_fun
integer n
real a(n),r
call cb_sub(a,n)
r = cb_fun(4)

следующие подписи обратных функций:

subroutine cb_sub(a,n)
    real dimension(n) :: a
    integer optional,check(len(a)>=n),depend(a) :: n=len(a)
end subroutine cb_sub
function cb_fun(e_4_e) result (r)
    integer :: e_4_e
    real :: r
end function cb_fun

Соответствующие предоставляемые пользователем функции Python тогда:

def cb_sub(a,[n]):
    ...
    return
def cb_fun(e_4_e):
    ...
    return r

См. также атрибут intent(callback).

parameter

Это указывает, что соответствующая переменная — параметр, и она должна иметь фиксированное значение. F2PY заменяет все вхождения параметра соответствующими значениями.

Расширения

<comment char>f2py ...

<array name>(_i[0],_i[1],...) = <init_expr>;

subroutine myrange(a,n)
  fortranname        ! myrange is a dummy wrapper
  integer intent(in) :: n
  real*8 intent(c,out),dimension(n),depend(n) :: a = _i[0]
end subroutine myrange

Расширенный селектор символов

F2PY расширяет спецификацию селектора символов, используемую в файле подписи или директиве F2PY, следующим образом:

<extended-charselector> := <charselector>
                        | (f2py_len= <len>)

См. Строки символов для использования.