Spec-Zone.ru › NumPy 1.18

Использование связывающих компонентов F2PY в Python

Все оболочки для подпрограмм Fortran/C, общих блоков или данных модуля Fortran 90, сгенерированные F2PY, представлены в Python как объекты типа fortran. Оболочки для подпрограмм являются вызываемыми объектами типа fortran, в то время как оболочки для данных Fortran имеют атрибуты, ссылающиеся на объекты данных.

Все объекты типа fortran имеют атрибут _cpointer, который содержит CObject, ссылающийся на указатель C соответствующей функции или переменной Fortran/C на уровне C. Такие CObject можно использовать в качестве аргумента обратного вызова сгенерированных функций F2PY для обхода уровня Python C/API вызова функций Python из Fortran или C, когда вычислительная часть таких функций реализована на C или Fortran и обернута с помощью F2PY (или любого другого инструмента, способного предоставить CObject функции).

Рассмотрим файл Fortran 77 ftype.f:

C FILE: FTYPE.F
      SUBROUTINE FOO(N)
      INTEGER N
Cf2py integer optional,intent(in) :: n = 13
      REAL A,X
      COMMON /DATA/ A,X(3)
      PRINT*, "IN FOO: N=",N," A=",A," X=[",X(1),X(2),X(3),"]"
      END
C END OF FTYPE.F

и создайте оболочку, используя f2py -c ftype.f -m ftype.

В Python:

>>> import ftype
>>> print ftype.__doc__
This module 'ftype' is auto-generated with f2py (version:2.28.198-1366).
Functions:
  foo(n=13)
COMMON blocks:
  /data/ a,x(3)
.
>>> type(ftype.foo),type(ftype.data)
(<type 'fortran'>, <type 'fortran'>)
>>> ftype.foo()
 IN FOO: N= 13 A=  0. X=[  0.  0.  0.]
>>> ftype.data.a = 3
>>> ftype.data.x = [1,2,3]
>>> ftype.foo()
 IN FOO: N= 13 A=  3. X=[  1.  2.  3.]
>>> ftype.data.x[1] = 45  
>>> ftype.foo(24)
 IN FOO: N= 24 A=  3. X=[  1.  45.  3.]
>>> ftype.data.x
array([  1.,  45.,   3.],'f')

Скалярные аргументы

В общем случае скалярный аргумент функции-оболочки, сгенерированной F2PY, может быть обычным скаляром Python (целым, вещественным, комплексным числом), а также произвольным объектом последовательности (списком, кортежем, массивом, строкой) скаляров. В последнем случае первый элемент объекта последовательности передаётся подпрограмме Fortran в качестве скалярного аргумента.

Обратите внимание, что при необходимости приведения типов и наличии возможной потери информации (например, при приведении типа float к типу integer или типа complex к типу float), F2PY не генерирует исключений. При приведении типа complex к типу real используется только действительная часть комплексного числа.

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

Рассмотрим следующий код Fortran 77:

C FILE: SCALAR.F
      SUBROUTINE FOO(A,B)
      REAL*8 A, B
Cf2py intent(in) a
Cf2py intent(inout) b
      PRINT*, "    A=",A," B=",B
      PRINT*, "INCREMENT A AND B"
      A = A + 1D0
      B = B + 1D0
      PRINT*, "NEW A=",A," B=",B
      END
C END OF FILE SCALAR.F

и оберните его, используя f2py -c -m scalar scalar.f.

В Python:

>>> import scalar
>>> print scalar.foo.__doc__
foo - Function signature:
  foo(a,b)
Required arguments:
  a : input float
  b : in/output rank-0 array(float,'d')
 
>>> scalar.foo(2,3)   
     A=  2. B=  3.
 INCREMENT A AND B
 NEW A=  3. B=  4.
>>> import numpy
>>> a=numpy.array(2)   # these are integer rank-0 arrays
>>> b=numpy.array(3)
>>> scalar.foo(a,b)
     A=  2. B=  3.
 INCREMENT A AND B
 NEW A=  3. B=  4.
>>> print a,b            # note that only b is changed in situ
2 4

Строковые аргументы

Функции-оболочки, сгенерированные F2PY, принимают (почти) любой объект Python в качестве строкового аргумента, str применяется для объектов, не являющихся строками. Исключение составляют массивы NumPy, которые должны иметь код типа 'c' или '1' при использовании в качестве строковых аргументов.

Строка может иметь произвольную длину при использовании её в качестве строкового аргумента для сгенерированной F2PY функции-оболочки. Если длина больше ожидаемой, строка усекается. Если длина меньше ожидаемой, выделяется дополнительная память и заполняется \0.

Поскольку строки Python неизменяемы, аргумент intent(inout) ожидает массивообразную версию строки, чтобы изменения in situ были эффективны.

Рассмотрим следующий код Fortran 77:

C FILE: STRING.F
      SUBROUTINE FOO(A,B,C,D)
      CHARACTER*5 A, B
      CHARACTER*(*) C,D
Cf2py intent(in) a,c
Cf2py intent(inout) b,d
      PRINT*, "A=",A
      PRINT*, "B=",B
      PRINT*, "C=",C
      PRINT*, "D=",D
      PRINT*, "CHANGE A,B,C,D"
      A(1:1) = 'A'
      B(1:1) = 'B'
      C(1:1) = 'C'
      D(1:1) = 'D'
      PRINT*, "A=",A
      PRINT*, "B=",B
      PRINT*, "C=",C
      PRINT*, "D=",D
      END
C END OF FILE STRING.F

и оберните его, используя f2py -c -m mystring string.f.

Сеанс Python:

>>> import mystring
>>> print mystring.foo.__doc__
foo - Function signature:
  foo(a,b,c,d)
Required arguments:
  a : input string(len=5)
  b : in/output rank-0 array(string(len=5),'c')
  c : input string(len=-1)
  d : in/output rank-0 array(string(len=-1),'c')

>>> import numpy
>>> a=numpy.array('123')
>>> b=numpy.array('123')
>>> c=numpy.array('123')
>>> d=numpy.array('123')
>>> mystring.foo(a,b,c,d)
 A=123
 B=123
 C=123
 D=123
 CHANGE A,B,C,D
 A=A23
 B=B23
 C=C23
 D=D23
>>> a.tostring(),b.tostring(),c.tostring(),d.tostring()
('123', 'B23', '123', 'D23')

Массивы аргументов

В общем случае массивы-аргументы сгенерированных функций-оболочек F2PY принимают произвольные последовательности, которые могут быть преобразованы в объекты массивов NumPy. Исключение составляют аргументы массивов intent(inout), которые всегда должны быть собственно-смежными и иметь соответствующий тип, в противном случае возникает исключение. Другое исключение составляют аргументы массивов intent(inplace), атрибуты которых будут изменены непосредственно, если аргумент имеет другой тип, чем ожидалось (см. атрибут intent(inplace) для получения дополнительной информации).

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

Существует два типа собственно-смежных массивов NumPy:

  • Массивы Fortran-смежные, когда данные хранятся по столбцам, т.е. индексация данных, как хранящихся в памяти, начинается с наименьшего измерения;
  • Массивы C-смежные или просто смежные, когда данные хранятся по строкам, т.е. индексация данных, как хранящихся в памяти, начинается с наибольшего измерения.

Для одномерных массивов эти понятия совпадают.

Например, массив 2x2 A является Fortran-смежным, если его элементы хранятся в памяти в следующем порядке:

A[0,0] A[1,0] A[0,1] A[1,1]

и C-смежным, если порядок такой:

A[0,0] A[0,1] A[1,0] A[1,1]

Для проверки того, является ли массив C-смежным, используйте метод .iscontiguous() массивов NumPy. Для проверки на Fortran-смежность все сгенерированные модули расширения F2PY предоставляют функцию has_column_major_storage(<array>). Эта функция эквивалентна <array>.flags.f_contiguous, но более эффективна.

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

Для преобразования входных массивов в порядок хранения по столбцам перед передачей их в подпрограммы Fortran используйте функцию as_column_major_storage(<array>), предоставляемую всеми сгенерированными модулями расширения F2PY.

Рассмотрим код Fortran 77:

C FILE: ARRAY.F
      SUBROUTINE FOO(A,N,M)
C
C     INCREMENT THE FIRST ROW AND DECREMENT THE FIRST COLUMN OF A
C
      INTEGER N,M,I,J
      REAL*8 A(N,M)
Cf2py intent(in,out,copy) a
Cf2py integer intent(hide),depend(a) :: n=shape(a,0), m=shape(a,1)
      DO J=1,M
         A(1,J) = A(1,J) + 1D0
      ENDDO
      DO I=1,N
         A(I,1) = A(I,1) - 1D0
      ENDDO
      END
C END OF FILE ARRAY.F

и оберните его, используя f2py -c -m arr array.f -DF2PY_REPORT_ON_ARRAY_COPY=1.

В Python:

>>> import arr
>>> from numpy import array
>>> print arr.foo.__doc__
foo - Function signature:
  a = foo(a,[overwrite_a])
Required arguments:
  a : input rank-2 array('d') with bounds (n,m)
Optional arguments:
  overwrite_a := 0 input int
Return objects:
  a : rank-2 array('d') with bounds (n,m)

>>> a=arr.foo([[1,2,3],
...            [4,5,6]])
copied an array using PyArray_CopyFromObject: size=6, elsize=8
>>> print a
[[ 1.  3.  4.]
 [ 3.  5.  6.]]
>>> a.iscontiguous(), arr.has_column_major_storage(a)
(0, 1)
>>> b=arr.foo(a)              # even if a is proper-contiguous
...                           # and has proper type, a copy is made
...                           # forced by intent(copy) attribute
...                           # to preserve its original contents
... 
copied an array using copy_ND_array: size=6, elsize=8
>>> print a
[[ 1.  3.  4.]
 [ 3.  5.  6.]]
>>> print b
[[ 1.  4.  5.]
 [ 2.  5.  6.]]
>>> b=arr.foo(a,overwrite_a=1) # a is passed directly to Fortran
...                            # routine and its contents is discarded
... 
>>> print a
[[ 1.  4.  5.]
 [ 2.  5.  6.]]
>>> print b
[[ 1.  4.  5.]
 [ 2.  5.  6.]]
>>> a is b                       # a and b are actually the same objects
1
>>> print arr.foo([1,2,3])       # different rank arrays are allowed
copied an array using PyArray_CopyFromObject: size=3, elsize=8
[ 1.  1.  2.]
>>> print arr.foo([[[1],[2],[3]]])
copied an array using PyArray_CopyFromObject: size=3, elsize=8
[ [[ 1.]
  [ 3.]
  [ 4.]]]
>>>
>>> # Creating arrays with column major data storage order:
...
>>> s = arr.as_column_major_storage(array([[1,2,3],[4,5,6]]))
copied an array using copy_ND_array: size=6, elsize=4
>>> arr.has_column_major_storage(s)
1
>>> print s
[[1 2 3]
 [4 5 6]]
>>> s2 = arr.as_column_major_storage(s)
>>> s2 is s    # an array with column major storage order 
               # is returned immediately
1

Аргументы обратного вызова

F2PY поддерживает вызов функций Python из кода Fortran или C.

Рассмотрим следующий код Fortran 77:

C FILE: CALLBACK.F
      SUBROUTINE FOO(FUN,R)
      EXTERNAL FUN
      INTEGER I
      REAL*8 R
Cf2py intent(out) r
      R = 0D0
      DO I=-5,5
         R = R + FUN(I)
      ENDDO
      END
C END OF FILE CALLBACK.F

и оберните его, используя f2py -c -m callback callback.f.

В Python:

>>> import callback
>>> print callback.foo.__doc__
foo - Function signature:
  r = foo(fun,[fun_extra_args])
Required arguments:
  fun : call-back function
Optional arguments:
  fun_extra_args := () input tuple
Return objects:
  r : float
Call-back functions:
  def fun(i): return r
  Required arguments:
    i : input int
  Return objects:
    r : float

>>> def f(i): return i*i
... 
>>> print callback.foo(f)     
110.0
>>> print callback.foo(lambda i:1)
11.0

В приведенном выше примере F2PY точно угадал сигнатуру функции обратного вызова. Однако иногда F2PY не может установить сигнатуру так, как хотелось бы, и тогда сигнатура функции обратного вызова должна быть изменена в файле сигнатуры вручную. Имена файлов сигнатуры могут содержать специальные модули (имена таких модулей содержат подстроку __user__), которые собирают различные сигнатуры функций обратного вызова. Аргументы обратного вызова в сигнатурах подпрограмм имеют атрибут external (см. также атрибут intent(callback)). Для связывания аргумента обратного вызова и его сигнатуры в блоке модуля __user__ используйте оператор use, как показано ниже. Одна и та же сигнатура аргумента обратного вызова может быть указана в различных сигнатурах подпрограмм.

Мы используем тот же код Fortran 77, что и в предыдущем примере, но теперь предположим, что F2PY не смог правильно угадать сигнатуры аргументов обратного вызова. Сначала мы создаём начальный файл сигнатуры callback2.pyf с помощью F2PY:

f2py -m callback2 -h callback2.pyf callback.f

Затем измените его следующим образом

!    -*- f90 -*-
python module __user__routines 
    interface
        function fun(i) result (r)
            integer :: i
            real*8 :: r
        end function fun
    end interface
end python module __user__routines

python module callback2
    interface
        subroutine foo(f,r)
            use __user__routines, f=>fun
            external f
            real*8 intent(out) :: r
        end subroutine foo
    end interface 
end python module callback2

Наконец, создайте модуль расширения, используя f2py -c callback2.pyf callback.f.

Пример сеанса Python будет идентичен предыдущему, за исключением того, что имена аргументов будут отличаться.

Иногда Fortran-пакет может потребовать, чтобы пользователи предоставили подпрограммы, которые пакет будет использовать. F2PY может построить интерфейс к таким подпрограммам, чтобы функции Python могли вызываться из Fortran.

Рассмотрим следующую подпрограмму Fortran 77, которая принимает массив и применяет функцию func к его элементам.

      subroutine calculate(x,n)
cf2py intent(callback) func
      external func
c     The following lines define the signature of func for F2PY:
cf2py real*8 y
cf2py y = func(y)
c
cf2py intent(in,out,copy) x
      integer n,i
      real*8 x(n)
      do i=1,n
         x(i) = func(x(i))
      end do
      end

Ожидается, что функция func была определена внешним образом. Для использования функции Python в качестве func, она должна иметь атрибут intent(callback) (он должен быть указан перед оператором external).

Наконец, создайте модуль расширения, используя f2py -c -m foo calculate.f

В Python:

>>> import foo
>>> foo.calculate(range(5), lambda x: x*x)
array([  0.,   1.,   4.,   9.,  16.])
>>> import math
>>> foo.calculate(range(5), math.exp)
array([  1.        ,   2.71828175,   7.38905621,  20.08553696,  54.59814835])

Функция включается в качестве аргумента вызова функции Python для подпрограммы Fortran, даже если она не входила в список аргументов подпрограммы Fortran. «Внешний» относится к функции C, сгенерированной f2py, а не к функции Python. Функция Python должна быть предоставлена функции C.

Функция обратного вызова также может быть явно задана в модуле. Тогда не нужно передавать функцию в списке аргументов функции Fortran. Это может быть желательно, если функция Fortran, вызывающая функцию обратного вызова Python, сама вызывается другой функцией Fortran.

Рассмотрим следующую подпрограмму Fortran 77:

      subroutine f1()
         print *, "in f1, calling f2 twice.."
         call f2()
         call f2()
         return
      end
      
      subroutine f2()
cf2py    intent(callback, hide) fpy
         external fpy
         print *, "in f2, calling f2py.."
         call fpy()
         return
      end

и оберните её, используя f2py -c -m pfromf extcallback.f.

В Python:

>>> import pfromf
>>> pfromf.f2()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
pfromf.error: Callback fpy not defined (as an argument or module pfromf attribute).

>>> def f(): print "python f"
... 
>>> pfromf.fpy = f
>>> pfromf.f2()
 in f2, calling f2py..
python f
>>> pfromf.f1()
 in f1, calling f2 twice..
 in f2, calling f2py..
python f
 in f2, calling f2py..
python f
>>>

Разрешение аргументов функций обратного вызова

Интерфейс, сгенерированный F2PY, очень гибкий по отношению к аргументам обратного вызова. Для каждого аргумента обратного вызова F2PY вводит дополнительный необязательный аргумент <name>_extra_args. Этот аргумент может быть использован для передачи дополнительных аргументов в предоставленные пользователем аргументы обратного вызова.

Если сгенерированная функция-оболочка F2PY ожидает следующий аргумент обратного вызова:

def fun(a_1,...,a_n):
   ...
   return x_1,...,x_k

но следующая функция Python

def gun(b_1,...,b_m):
   ...
   return y_1,...,y_l

предоставляется пользователем, и в дополнение,

fun_extra_args = (e_1,...,e_p)

используется, тогда при вызове аргумента обратного вызова gun функцией Fortran или C применяются следующие правила:

  • Если p == 0, то вызывается gun(a_1, ..., a_q), здесь q = min(m, n).
  • Если n + p <= m, то вызывается gun(a_1, ..., a_n, e_1, ..., e_p).
  • Если p <= m < n + p, то вызывается gun(a_1, ..., a_q, e_1, ..., e_p) здесь q=m-p.
  • Если p > m, то вызывается gun(e_1, ..., e_m).
  • Если n + p меньше числа требуемых аргументов для gun, то возникает исключение.

Функция gun может возвращать любое количество объектов в виде кортежа. Затем применяются следующие правила:

  • Если k < l, то значения y_{k + 1}, ..., y_l игнорируются.
  • Если k > l, то устанавливаются только значения x_1, ..., x_l.

Общие блоки

F2PY генерирует оболочки для общих блоков common, определённых в блоке сигнатуры подпрограммы. Общие блоки видны всем кодам Fortran, связанным с текущим модулем расширения, но не другим модулям расширения (это ограничение обусловлено тем, как Python импортирует общие библиотеки). В Python оболочки F2PY для общих блоков common являются объектами типа fortran, которые имеют (динамические) атрибуты, связанные с членами данных общих блоков. При обращении эти атрибуты возвращают объекты массивов NumPy (многомерные массивы являются Fortran-смежными), которые напрямую связаны с членами данных в общих блоках. Члены данных могут изменяться путём прямого присваивания или путём изменений in situ соответствующих объектов массивов.

Рассмотрим следующий код Fortran 77:

C FILE: COMMON.F
      SUBROUTINE FOO
      INTEGER I,X
      REAL A
      COMMON /DATA/ I,X(4),A(2,3)
      PRINT*, "I=",I
      PRINT*, "X=[",X,"]"
      PRINT*, "A=["
      PRINT*, "[",A(1,1),",",A(1,2),",",A(1,3),"]"
      PRINT*, "[",A(2,1),",",A(2,2),",",A(2,3),"]"
      PRINT*, "]"
      END
C END OF COMMON.F

и оберните его, используя f2py -c -m common common.f.

В Python:

>>> import common
>>> print common.data.__doc__
i - 'i'-scalar
x - 'i'-array(4)
a - 'f'-array(2,3)

>>> common.data.i = 5
>>> common.data.x[1] = 2 
>>> common.data.a = [[1,2,3],[4,5,6]]
>>> common.foo()
 I= 5
 X=[ 0 2 0 0]
 A=[
 [  1.,  2.,  3.]
 [  4.,  5.,  6.]
 ]
>>> common.data.a[1] = 45
>>> common.foo()
 I= 5
 X=[ 0 2 0 0]
 A=[
 [  1.,  2.,  3.]
 [  45.,  45.,  45.]
 ]
>>> common.data.a                 # a is Fortran-contiguous
array([[  1.,   2.,   3.],
       [ 45.,  45.,  45.]],'f')

Данные модуля Fortran 90

Интерфейс F2PY для данных модуля Fortran 90 аналогичен общим блокам Fortran 77.

Рассмотрим следующий код Fortran 90:

module mod
  integer i
  integer :: x(4)
  real, dimension(2,3) :: a
  real, allocatable, dimension(:,:) :: b 
contains
  subroutine foo
    integer k
    print*, "i=",i
    print*, "x=[",x,"]"
    print*, "a=["
    print*, "[",a(1,1),",",a(1,2),",",a(1,3),"]"
    print*, "[",a(2,1),",",a(2,2),",",a(2,3),"]"
    print*, "]"
    print*, "Setting a(1,2)=a(1,2)+3"
    a(1,2) = a(1,2)+3
  end subroutine foo
end module mod

и оберните его, используя f2py -c -m moddata moddata.f90.

В Python:

>>> import moddata
>>> print moddata.mod.__doc__
i - 'i'-scalar
x - 'i'-array(4)
a - 'f'-array(2,3)
foo - Function signature:
  foo()


>>> moddata.mod.i = 5  
>>> moddata.mod.x[:2] = [1,2]
>>> moddata.mod.a = [[1,2,3],[4,5,6]]
>>> moddata.mod.foo()                
 i=           5
 x=[           1           2           0           0 ]
 a=[
 [   1.000000     ,   2.000000     ,   3.000000     ]
 [   4.000000     ,   5.000000     ,   6.000000     ]
 ]
 Setting a(1,2)=a(1,2)+3
>>> moddata.mod.a               # a is Fortran-contiguous
array([[ 1.,  5.,  3.],
       [ 4.,  5.,  6.]],'f')

Выделяемые массивы

F2PY имеет базовую поддержку выделяемых массивов модулей Fortran 90.

Рассмотрим следующий код Fortran 90:

module mod
  real, allocatable, dimension(:,:) :: b 
contains
  subroutine foo
    integer k
    if (allocated(b)) then
       print*, "b=["
       do k = 1,size(b,1)
          print*, b(k,1:size(b,2))
       enddo
       print*, "]"
    else
       print*, "b is not allocated"
    endif
  end subroutine foo
end module mod

и оберните его с помощью f2py -c -m allocarr allocarr.f90.

В Python:

>>> import allocarr 
>>> print allocarr.mod.__doc__
b - 'f'-array(-1,-1), not allocated
foo - Function signature:
  foo()

>>> allocarr.mod.foo()  
 b is not allocated
>>> allocarr.mod.b = [[1,2,3],[4,5,6]]         # allocate/initialize b
>>> allocarr.mod.foo()
 b=[
   1.000000       2.000000       3.000000    
   4.000000       5.000000       6.000000    
 ]
>>> allocarr.mod.b                             # b is Fortran-contiguous
array([[ 1.,  2.,  3.],
       [ 4.,  5.,  6.]],'f')
>>> allocarr.mod.b = [[1,2,3],[4,5,6],[7,8,9]] # reallocate/initialize b
>>> allocarr.mod.foo()
 b=[
   1.000000       2.000000       3.000000    
   4.000000       5.000000       6.000000    
   7.000000       8.000000       9.000000    
 ]
>>> allocarr.mod.b = None                      # deallocate array
>>> allocarr.mod.foo()
 b is not allocated

© 2005–2020 NumPy Developers
Licensed under the 3-clause BSD License.
https://numpy.org/doc/1.18/f2py/python-usage.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API