File: index.rst

package info (click to toggle)
numpy 1%3A2.3.3%2Bds-2
  • links: PTS, VCS
  • area: main
  • in suites:
  • size: 85,944 kB
  • sloc: python: 255,476; asm: 232,483; ansic: 212,559; cpp: 157,437; f90: 1,575; sh: 845; fortran: 567; makefile: 427; sed: 139; xml: 109; java: 97; perl: 82; cs: 62; javascript: 53; objc: 33; lex: 13; yacc: 9
file content (118 lines) | stat: -rw-r--r-- 3,436 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
.. _f2py-bldsys:

=======================
F2PY and build systems
=======================

In this section we will cover the various popular build systems and their usage
with ``f2py``.

.. versionchanged:: NumPy 1.26.x

   The default build system for ``f2py`` has traditionally been through the
   enhanced ``numpy.distutils`` module. This module is based on ``distutils``
   which was removed in ``Python 3.12.0`` in **October 2023**. Like the rest of
   NumPy and SciPy, ``f2py`` uses ``meson`` now, see
   :ref:`distutils-status-migration` for some more details.

    All changes to ``f2py`` are tested on SciPy, so their `CI configuration`_ is
    always supported.


.. note::

   See :ref:`f2py-meson-distutils` for migration information.


Basic concepts
===============

Building an extension module which includes Python and Fortran consists of:

- Fortran source(s)
- One or more generated files from ``f2py``

  + A ``C`` wrapper file is always created
  + Code with modules require an additional ``.f90`` wrapper
  + Code with functions generate an additional ``.f`` wrapper

- ``fortranobject.{c,h}``

  + Distributed with ``numpy``
  + Can be queried via ``python -c "import numpy.f2py; print(numpy.f2py.get_include())"``

- NumPy headers

  + Can be queried via ``python -c "import numpy; print(numpy.get_include())"``

- Python libraries and development headers

Broadly speaking there are three cases which arise when considering the outputs of ``f2py``:

Fortran 77 programs
   - Input file ``blah.f``
   - Generates

     + ``blahmodule.c``
     + ``blah-f2pywrappers.f``

   When no ``COMMON`` blocks are present only a ``C`` wrapper file is generated.
   Wrappers are also generated to rewrite assumed shape arrays as automatic
   arrays.

Fortran 90 programs
   - Input file ``blah.f90``
   - Generates:

     + ``blahmodule.c``
     + ``blah-f2pywrappers.f``
     + ``blah-f2pywrappers2.f90``

   The ``f90`` wrapper is used to handle code which is subdivided into
   modules. The ``f`` wrapper makes ``subroutines`` for  ``functions``. It
   rewrites assumed shape arrays as automatic arrays.

Signature files
   - Input file ``blah.pyf``
   - Generates:

     + ``blahmodule.c``
     + ``blah-f2pywrappers2.f90`` (occasionally)
     + ``blah-f2pywrappers.f`` (occasionally)

   Signature files ``.pyf`` do not signal their language standard via the file
   extension, they may generate the F90 and F77 specific wrappers depending on
   their contents; which shifts the burden of checking for generated files onto
   the build system.

.. versionchanged:: NumPy ``1.22.4``

   ``f2py`` will deterministically generate wrapper files based on the input
   file Fortran standard (F77 or greater).  ``--skip-empty-wrappers`` can be
   passed to ``f2py`` to restore the previous behaviour of only generating
   wrappers when needed by the input .


In theory keeping the above requirements in hand, any build system can be
adapted to generate ``f2py`` extension modules. Here we will cover a subset of
the more popular systems.

.. note::
   ``make`` has no place in a modern multi-language setup, and so is not
   discussed further.

Build systems
==============

.. toctree::
   :maxdepth: 2

   distutils
   meson
   cmake
   skbuild
   distutils-to-meson

.. _`issue 20385`: https://github.com/numpy/numpy/issues/20385

.. _`CI configuration`: https://docs.scipy.org/doc/scipy/dev/toolchain.html#official-builds