diff options
Diffstat (limited to 'doc/source/f2py/python-usage.rst')
| -rw-r--r-- | doc/source/f2py/python-usage.rst | 266 |
1 files changed, 134 insertions, 132 deletions
diff --git a/doc/source/f2py/python-usage.rst b/doc/source/f2py/python-usage.rst index 65c0cec64..ef8ccd7dd 100644 --- a/doc/source/f2py/python-usage.rst +++ b/doc/source/f2py/python-usage.rst @@ -4,74 +4,76 @@ Using F2PY bindings in Python All wrappers for Fortran/C routines, common blocks, or for Fortran 90 module data generated by F2PY are exposed to Python as ``fortran`` -type objects. Routine wrappers are callable ``fortran`` type objects +type objects. Routine wrappers are callable ``fortran`` type objects while wrappers to Fortran data have attributes referring to data objects. -All ``fortran`` type objects have attribute ``_cpointer`` that contains -CObject referring to the C pointer of the corresponding Fortran/C -function or variable in C level. Such CObjects can be used as a -callback argument of F2PY generated functions to bypass Python C/API -layer of calling Python functions from Fortran or C when the -computational part of such functions is implemented in C or Fortran -and wrapped with F2PY (or any other tool capable of providing CObject -of a function). +All ``fortran`` type objects have an attribute ``_cpointer`` that contains a +``CObject`` referring to the C pointer of the corresponding Fortran/C function +or variable at the C level. Such ``CObjects`` can be used as a callback argument +for F2PY generated functions to bypass the Python C/API layer for calling Python +functions from Fortran or C when the computational aspects of such functions are +implemented in C or Fortran and wrapped with F2PY (or any other tool capable of +providing the ``CObject`` of a function). -Consider a Fortran 77 file ``ftype.f``: +Consider a Fortran 77 file ```ftype.f``: - .. include:: ftype.f - :literal: + .. literalinclude:: ./code/ftype.f + :language: fortran -and build a wrapper using ``f2py -c ftype.f -m ftype``. +and a wrapper built using ``f2py -c ftype.f -m ftype``. In Python: - .. include:: ftype_session.dat - :literal: + .. literalinclude:: ./code/results/ftype_session.dat + :language: python Scalar arguments ================= -In general, a scalar argument of a F2PY generated wrapper function can +In general, a scalar argument for a F2PY generated wrapper function can be an ordinary Python scalar (integer, float, complex number) as well as an arbitrary sequence object (list, tuple, array, string) of scalars. In the latter case, the first element of the sequence object is passed to Fortran routine as a scalar argument. -Note that when type-casting is required and there is possible loss of -information (e.g. when type-casting float to integer or complex to -float), F2PY does not raise any exception. In complex to real -type-casting only the real part of a complex number is used. +.. note:: + + * When type-casting is required and there is possible loss of information via + narrowing e.g. when type-casting float to integer or complex to float, F2PY + *does not* raise an exception. -``intent(inout)`` scalar arguments are assumed to be array objects in -order to have *in situ* changes be effective. It is recommended to use -arrays with proper type but also other types work. + * For complex to real type-casting only the real part of a complex number is used. + + * ``intent(inout)`` scalar arguments are assumed to be array objects in + order to have *in situ* changes be effective. It is recommended to use + arrays with proper type but also other types work. Consider the following Fortran 77 code: - .. include:: scalar.f - :literal: + .. literalinclude:: ./code/scalar.f + :language: fortran and wrap it using ``f2py -c -m scalar scalar.f``. In Python: - .. include:: scalar_session.dat - :literal: + .. literalinclude:: ./code/results/scalar_session.dat + :language: python String arguments ================= -F2PY generated wrapper functions accept (almost) any Python object as -a string argument, ``str`` is applied for non-string objects. +F2PY generated wrapper functions accept almost any Python object as +a string argument, since ``str`` is applied for non-string objects. Exceptions are NumPy arrays that must have type code ``'c'`` or ``'1'`` when used as string arguments. -A string can have arbitrary length when using it as a string argument -to F2PY generated wrapper function. If the length is greater than -expected, the string is truncated. If the length is smaller than +A string can have an arbitrary length when used as a string argument +for an F2PY generated wrapper function. If the length is greater than +expected, the string is truncated silently. If the length is smaller than expected, additional memory is allocated and filled with ``\0``. Because Python strings are immutable, an ``intent(inout)`` argument @@ -79,43 +81,43 @@ expects an array version of a string in order to have *in situ* changes be effec Consider the following Fortran 77 code: - .. include:: string.f - :literal: + .. literalinclude:: ./code/string.f + :language: fortran and wrap it using ``f2py -c -m mystring string.f``. Python session: - .. include:: string_session.dat - :literal: + .. literalinclude:: ./code/results/string_session.dat + :language: python Array arguments ================ -In general, array arguments of F2PY generated wrapper functions accept -arbitrary sequences that can be transformed to NumPy array objects. -An exception is ``intent(inout)`` array arguments that always must be -proper-contiguous and have proper type, otherwise an exception is -raised. Another exception is ``intent(inplace)`` array arguments that -attributes will be changed *in situ* if the argument has different type -than expected (see ``intent(inplace)`` attribute for more -information). - -In general, if a NumPy array is proper-contiguous and has a proper -type then it is directly passed to wrapped Fortran/C function. -Otherwise, an element-wise copy of an input array is made and the -copy, being proper-contiguous and with proper type, is used as an -array argument. +In general, array arguments for F2PY generated wrapper functions accept +arbitrary sequences that can be transformed to NumPy array objects. There are +two notable exceptions: + +* ``intent(inout)`` array arguments must always be proper-contiguous (defined below) and have a + compatible ``dtype``, otherwise an exception is raised. +* ``intent(inplace)`` array arguments will be changed *in situ* if the argument + has a different type than expected (see the ``intent(inplace)`` attribute for + more information). + +In general, if a NumPy array is proper-contiguous and has a proper type then it +is directly passed to the wrapped Fortran/C function. Otherwise, an element-wise +copy of the input array is made and the copy, being proper-contiguous and with +proper type, is used as the array argument. There are two types of proper-contiguous NumPy arrays: -* Fortran-contiguous arrays when data is stored column-wise, - i.e. indexing of data as stored in memory starts from the lowest +* Fortran-contiguous arrays refer to data that is stored columnwise, + i.e. the indexing of data as stored in memory starts from the lowest dimension; -* C-contiguous or simply contiguous arrays when data is stored - row-wise, i.e. indexing of data as stored in memory starts from the - highest dimension. +* C-contiguous, or simply contiguous arrays, refer to data that is stored + rowwise, i.e. the indexing of data as stored in memory starts from the highest + dimension. For one-dimensional arrays these notions coincide. @@ -132,30 +134,29 @@ To test whether an array is C-contiguous, use the ``.flags.c_contiguous`` attribute of NumPy arrays. To test for Fortran contiguity, use the ``.flags.f_contiguous`` attribute. -Usually there is no need to worry about how the arrays are stored in -memory and whether the wrapped functions, being either Fortran or C -functions, assume one or another storage order. F2PY automatically -ensures that wrapped functions get arguments with proper storage -order; the corresponding algorithm is designed to make copies of -arrays only when absolutely necessary. However, when dealing with very -large multidimensional input arrays with sizes close to the size of -the physical memory in your computer, then a care must be taken to use -always proper-contiguous and proper type arguments. +Usually there is no need to worry about how the arrays are stored in memory and +whether the wrapped functions, being either Fortran or C functions, assume one +or another storage order. F2PY automatically ensures that wrapped functions get +arguments with the proper storage order; the underlying algorithm is designed to +make copies of arrays only when absolutely necessary. However, when dealing with +very large multidimensional input arrays with sizes close to the size of the +physical memory in your computer, then care must be taken to ensure the usage of +proper-contiguous and proper type arguments. To transform input arrays to column major storage order before passing them to Fortran routines, use the function ``numpy.asfortranarray(<array>)``. Consider the following Fortran 77 code: - .. include:: array.f - :literal: + .. literalinclude:: ./code/array.f + :language: fortran and wrap it using ``f2py -c -m arr array.f -DF2PY_REPORT_ON_ARRAY_COPY=1``. In Python: - .. include:: array_session.dat - :literal: + .. literalinclude:: ./code/results/array_session.dat + :language: python .. _Call-back arguments: @@ -166,31 +167,32 @@ F2PY supports calling Python functions from Fortran or C codes. Consider the following Fortran 77 code: - .. include:: callback.f - :literal: + .. literalinclude:: ./code/callback.f + :language: fortran and wrap it using ``f2py -c -m callback callback.f``. In Python: - .. include:: callback_session.dat - :literal: + .. literalinclude:: ./code/results/callback_session.dat + :language: python In the above example F2PY was able to guess accurately the signature -of a call-back function. However, sometimes F2PY cannot establish the -signature as one would wish and then the signature of a call-back -function must be modified in the signature file manually. Namely, -signature files may contain special modules (the names of such modules -contain a substring ``__user__``) that collect various signatures of -call-back functions. Callback arguments in routine signatures have -attribute ``external`` (see also ``intent(callback)`` attribute). To -relate a callback argument and its signature in ``__user__`` module -block, use ``use`` statement as illustrated below. The same signature -of a callback argument can be referred in different routine +of the call-back function. However, sometimes F2PY cannot establish the +appropriate signature; in these cases the signature of the call-back +function must be explicitly defined in the signature file. + +To facilitate this, signature files may contain special modules (the names of +these modules contain the special ``__user__`` sub-string) that defines the +various signatures for call-back functions. Callback arguments in routine +signatures have the ``external`` attribute (see also the ``intent(callback)`` +attribute). To relate a callback argument with its signature in a ``__user__`` +module block, a ``use`` statement can be utilized as illustrated below. The same +signature for a callback argument can be referred to in different routine signatures. -We use the same Fortran 77 code as in previous example but now -we'll pretend that F2PY was not able to guess the signatures of +We use the same Fortran 77 code as in the previous example but now +we will pretend that F2PY was not able to guess the signatures of call-back arguments correctly. First, we create an initial signature file ``callback2.pyf`` using F2PY:: @@ -198,40 +200,40 @@ file ``callback2.pyf`` using F2PY:: Then modify it as follows - .. include:: callback2.pyf + .. include:: ./code/callback2.pyf :literal: -Finally, build the extension module using ``f2py -c callback2.pyf callback.f``. +Finally, we build the extension module using ``f2py -c callback2.pyf callback.f``. -An example Python session would be identical to the previous example -except that argument names would differ. +An example Python session for this snippet would be identical to the previous +example except that the argument names would differ. Sometimes a Fortran package may require that users provide routines that the package will use. F2PY can construct an interface to such -routines so that Python functions could be called from Fortran. +routines so that Python functions can be called from Fortran. -Consider the following Fortran 77 subroutine that takes an array +Consider the following Fortran 77 subroutine that takes an array as its input and applies a function ``func`` to its elements. - .. include:: calculate.f - :literal: + .. literalinclude:: ./code/calculate.f + :language: fortran -It is expected that function ``func`` has been defined -externally. In order to use a Python function as ``func``, it must -have an attribute ``intent(callback)`` (it must be specified before -the ``external`` statement). +The Fortran code expects that the function ``func`` has been defined externally. +In order to use a Python function for ``func``, it must have an attribute +``intent(callback)`` and, it must be specified before the ``external`` statement. Finally, build an extension module using ``f2py -c -m foo calculate.f`` In Python: - .. include:: calculate_session.dat - :literal: + .. literalinclude:: ./code/results/calculate_session.dat + :language: python -The function is included as an argument to the python function call to -the Fortran subroutine even though it was *not* in the Fortran subroutine argument -list. The "external" refers to the C function generated by f2py, not the python -function itself. The python function must be supplied to the C function. +The function is included as an argument to the python function call to the +Fortran subroutine even though it was *not* in the Fortran subroutine argument +list. The "external" keyword refers to the C function generated by f2py, not the +python function itself. The python function is essentially being supplied to the +C function. The callback function may also be explicitly set in the module. Then it is not necessary to pass the function in the argument list to @@ -240,24 +242,24 @@ the python callback function is itself called by another Fortran function. Consider the following Fortran 77 subroutine: - .. include:: extcallback.f - :literal: + .. literalinclude:: ./code/extcallback.f + :language: fortran and wrap it using ``f2py -c -m pfromf extcallback.f``. In Python: - .. include:: extcallback_session.dat - :literal: + .. literalinclude:: ./code/results/extcallback_session.dat + :language: python Resolving arguments to call-back functions ------------------------------------------- +=========================================== -F2PY generated interface is very flexible with respect to call-back +F2PY generated interfaces are very flexible with respect to call-back arguments. For each call-back argument an additional optional argument ``<name>_extra_args`` is introduced by F2PY. This argument can be used to pass extra arguments to user provided call-back -arguments. +functions. If a F2PY generated wrapper function expects the following call-back argument:: @@ -281,7 +283,7 @@ is provided by a user, and in addition, fun_extra_args = (e_1,...,e_p) is used, then the following rules are applied when a Fortran or C -function calls the call-back argument ``gun``: +function evaluates the call-back argument ``gun``: * If ``p == 0`` then ``gun(a_1, ..., a_q)`` is called, here ``q = min(m, n)``. @@ -292,8 +294,8 @@ function calls the call-back argument ``gun``: * If ``n + p`` is less than the number of required arguments to ``gun`` then an exception is raised. -The function ``gun`` may return any number of objects as a tuple. Then -following rules are applied: +If the function ``gun`` may return any number of objects as a tuple; then +the following rules are applied: * If ``k < l``, then ``y_{k + 1}, ..., y_l`` are ignored. * If ``k > l``, then only ``x_1, ..., x_l`` are set. @@ -303,62 +305,62 @@ Common blocks ============== F2PY generates wrappers to ``common`` blocks defined in a routine -signature block. Common blocks are visible by all Fortran codes linked -with the current extension module, but not to other extension modules -(this restriction is due to how Python imports shared libraries). In +signature block. Common blocks are visible to all Fortran codes linked +to the current extension module, but not to other extension modules +(this restriction is due to the way Python imports shared libraries). In Python, the F2PY wrappers to ``common`` blocks are ``fortran`` type -objects that have (dynamic) attributes related to data members of -common blocks. When accessed, these attributes return as NumPy array -objects (multidimensional arrays are Fortran-contiguous) that +objects that have (dynamic) attributes related to the data members of +the common blocks. When accessed, these attributes return as NumPy array +objects (multidimensional arrays are Fortran-contiguous) which directly link to data members in common blocks. Data members can be changed by direct assignment or by in-place changes to the corresponding array objects. Consider the following Fortran 77 code: - .. include:: common.f - :literal: + .. literalinclude:: ./code/common.f + :language: fortran and wrap it using ``f2py -c -m common common.f``. In Python: - .. include:: common_session.dat - :literal: + .. literalinclude:: ./code/results/common_session.dat + :language: python Fortran 90 module data ======================= -The F2PY interface to Fortran 90 module data is similar to Fortran 77 +The F2PY interface to Fortran 90 module data is similar to the handling of Fortran 77 common blocks. Consider the following Fortran 90 code: - .. include:: moddata.f90 - :literal: + .. literalinclude:: ./code/moddata.f90 + :language: fortran and wrap it using ``f2py -c -m moddata moddata.f90``. In Python: - .. include:: moddata_session.dat - :literal: + .. literalinclude:: ./code/results/moddata_session.dat + :language: python Allocatable arrays -------------------- +=================== F2PY has basic support for Fortran 90 module allocatable arrays. Consider the following Fortran 90 code: - .. include:: allocarr.f90 - :literal: + .. literalinclude:: ./code/allocarr.f90 + :language: fortran and wrap it using ``f2py -c -m allocarr allocarr.f90``. In Python: - .. include:: allocarr_session.dat - :literal: + .. literalinclude:: ./code/results/allocarr_session.dat + :language: python |