{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "f2py:f2py-examples", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Below are some examples of F2PY usage. This list is not comprehensive, but can be used as a starting point when wrapping your own code." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The best place to look for examples is the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy issue tracker" } ], "url": "https://github.com/numpy/numpy/issues?q=is%3Aissue+label%3A%22component%3A+numpy.f2py%22+is%3Aclosed", "title": "" }, { "__type": "Text", "__tag": 4046, "value": ", or the test cases for " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py" }, { "__type": "Text", "__tag": 4046, "value": ". Some more use cases are in " }, { "__type": "CrossRef", "__tag": 4002, "value": "f2py-boilerplating", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "f2py:advanced:boilerplating" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "F2PY examples" } ], "level": 0, "target": "f2py-examples" }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "F2PY walkthrough: a basic extension module" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Consider the following subroutine, contained in a file named " }, { "__type": "InlineCode", "__tag": 4051, "value": "add.f" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This routine simply adds the elements in two contiguous arrays and places the result in a third. The memory for all three arrays must be provided by the calling routine. A very basic interface to this routine can be automatically generated by f2py " } ] }, { "__type": "Code", "__tag": 4050, "value": "python -m numpy.f2py -m add add.f", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This command will produce an extension module named " }, { "__type": "InlineCode", "__tag": 4051, "value": "addmodule.c" }, { "__type": "Text", "__tag": 4046, "value": " in the current directory. This extension module can now be compiled and used from Python just like any other extension module." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Creating source for a basic extension module" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You can also get f2py to both compile " }, { "__type": "InlineCode", "__tag": 4051, "value": "add.f" }, { "__type": "Text", "__tag": 4046, "value": " along with the produced extension module leaving only a shared-library extension file that can be imported from Python " } ] }, { "__type": "Code", "__tag": 4050, "value": "python -m numpy.f2py -c -m add add.f", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This command produces a Python extension module compatible with your platform. This module may then be imported from Python. It will contain a method for each subroutine in " }, { "__type": "InlineCode", "__tag": 4051, "value": "add" }, { "__type": "Text", "__tag": 4046, "value": ". The docstring of each method contains information about how the module method may be called:" } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import add\n>>> print(add.zadd.__doc__)\nzadd(a,b,c,n)\n\nWrapper for ``zadd``.\n\nParameters\n----------\na : input rank-1 array('D') with bounds (*)\nb : input rank-1 array('D') with bounds (*)\nc : input rank-1 array('D') with bounds (*)\nn : input int", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Creating a compiled extension module" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The default interface is a very literal translation of the Fortran code into Python. The Fortran array arguments are converted to NumPy arrays and the integer argument should be mapped to a " }, { "__type": "InlineCode", "__tag": 4051, "value": "C" }, { "__type": "Text", "__tag": 4046, "value": " integer. The interface will attempt to convert all arguments to their required types (and shapes) and issue an error if unsuccessful. However, because " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py" }, { "__type": "Text", "__tag": 4046, "value": " knows nothing about the semantics of the arguments (such that " }, { "__type": "InlineCode", "__tag": 4051, "value": "C" }, { "__type": "Text", "__tag": 4046, "value": " is an output and " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " should really match the array sizes), it is possible to abuse this function in ways that can cause Python to crash. For example:" } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> add.zadd([1, 2, 3], [1, 2], [3, 4], 1000)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "will cause a program crash on most systems. Under the hood, the lists are being converted to arrays but then the underlying " }, { "__type": "InlineCode", "__tag": 4051, "value": "add" }, { "__type": "Text", "__tag": 4046, "value": " function is told to cycle way beyond the borders of the allocated memory." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In order to improve the interface, " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py" }, { "__type": "Text", "__tag": 4046, "value": " supports directives. This is accomplished by constructing a signature file. It is usually best to start from the interfaces that " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py" }, { "__type": "Text", "__tag": 4046, "value": " produces in that file, which correspond to the default behavior. To get " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py" }, { "__type": "Text", "__tag": 4046, "value": " to generate the interface file use the " }, { "__type": "InlineCode", "__tag": 4051, "value": "-h" }, { "__type": "Text", "__tag": 4046, "value": " option " } ] }, { "__type": "Code", "__tag": 4050, "value": "python -m numpy.f2py -h add.pyf -m add add.f", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This command creates the " }, { "__type": "InlineCode", "__tag": 4051, "value": "add.pyf" }, { "__type": "Text", "__tag": 4046, "value": " file in the current directory. The section of this file corresponding to " }, { "__type": "InlineCode", "__tag": 4051, "value": "zadd" }, { "__type": "Text", "__tag": 4046, "value": " is:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "By placing intent directives and checking code, the interface can be cleaned up quite a bit so the Python module method is both easier to use and more robust to malformed inputs." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The intent directive, intent(out) is used to tell f2py that " }, { "__type": "InlineCode", "__tag": 4051, "value": "c" }, { "__type": "Text", "__tag": 4046, "value": " is an output variable and should be created by the interface before being passed to the underlying code. The intent(hide) directive tells f2py to not allow the user to specify the variable, " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": ", but instead to get it from the size of " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": ". The depend( " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " ) directive is necessary to tell f2py that the value of n depends on the input a (so that it won't try to create the variable n until the variable a is created)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "After modifying " }, { "__type": "InlineCode", "__tag": 4051, "value": "add.pyf" }, { "__type": "Text", "__tag": 4046, "value": ", the new Python module file can be generated by compiling both " }, { "__type": "InlineCode", "__tag": 4051, "value": "add.f" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "add.pyf" }, { "__type": "Text", "__tag": 4046, "value": " " } ] }, { "__type": "Code", "__tag": 4050, "value": "python -m numpy.f2py -c add.pyf add.f", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The new interface's docstring is:" } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import add\n>>> print(add.zadd.__doc__)\nc = zadd(a,b)\n\nWrapper for ``zadd``.\n\nParameters\n----------\na : input rank-1 array('D') with bounds (n)\nb : input rank-1 array('D') with bounds (n)\n\nReturns\n-------\nc : rank-1 array('D') with bounds (n)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Now, the function can be called in a much more robust way:" } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> add.zadd([1, 2, 3], [4, 5, 6])\narray([5.+0.j, 7.+0.j, 9.+0.j])", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Notice the automatic conversion to the correct format that occurred." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Improving the basic interface" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The robust interface of the previous section can also be generated automatically by placing the variable directives as special comments in the original Fortran code." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For projects where the Fortran code is being actively developed, this may be preferred." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Thus, if the source code is modified to contain:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Then, one can compile the extension module using " } ] }, { "__type": "Code", "__tag": 4050, "value": "python -m numpy.f2py -c -m add add.f", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The resulting signature for the function add.zadd is exactly the same one that was created previously. If the original source code had contained " }, { "__type": "InlineCode", "__tag": 4051, "value": "A(N)" }, { "__type": "Text", "__tag": 4046, "value": " instead of " }, { "__type": "InlineCode", "__tag": 4051, "value": "A(*)" }, { "__type": "Text", "__tag": 4046, "value": " and so forth with " }, { "__type": "InlineCode", "__tag": 4051, "value": "B" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "C" }, { "__type": "Text", "__tag": 4046, "value": ", then nearly the same interface can be obtained by placing the " }, { "__type": "InlineCode", "__tag": 4051, "value": "INTENT(OUT) :: C" }, { "__type": "Text", "__tag": 4046, "value": " comment line in the source code. The only difference is that " }, { "__type": "InlineCode", "__tag": 4051, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " would be an optional input that would default to the length of " }, { "__type": "InlineCode", "__tag": 4051, "value": "A" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Inserting directives in Fortran source" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This example shows a function that filters a two-dimensional array of double precision floating-point numbers using a fixed averaging filter. The advantage of using Fortran to index into multi-dimensional arrays should be clear from this example." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This code can be compiled and linked into an extension module named filter using " } ] }, { "__type": "Code", "__tag": 4050, "value": "python -m numpy.f2py -c -m filter filter.f", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This will produce an extension module in the current directory with a method named " }, { "__type": "InlineCode", "__tag": 4051, "value": "dfilter2d" }, { "__type": "Text", "__tag": 4046, "value": " that returns a filtered version of the input." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "A filtering example" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Consider the following code, saved in the file " }, { "__type": "InlineCode", "__tag": 4051, "value": "myroutine.f90" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Wrapping this with " }, { "__type": "InlineCode", "__tag": 4051, "value": "python -m numpy.f2py -c myroutine.f90 -m myroutine" }, { "__type": "Text", "__tag": 4046, "value": ", we can do the following in Python " } ] }, { "__type": "Code", "__tag": 4050, "value": " >>> import numpy as np\n\t>>> import myroutine\n\t>>> x = myroutine.s(2, 3, np.array([5, 6, 7]))\n\t>>> x\n\tarray([[5., 0., 0.],\n [0., 0., 0.]])", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Now, instead of generating the extension module directly, we will create a signature file for this subroutine first. This is a common pattern for multi-step extension module generation. In this case, after running" } ] }, { "__type": "Code", "__tag": 4050, "value": "python -m numpy.f2py myroutine.f90 -m myroutine -h myroutine.pyf", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "the following signature file is generated:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Now, if we run " }, { "__type": "InlineCode", "__tag": 4051, "value": "python -m numpy.f2py -c myroutine.pyf myroutine.f90" }, { "__type": "Text", "__tag": 4046, "value": " we see an error; note that the signature file included a " }, { "__type": "InlineCode", "__tag": 4051, "value": "depend(m,n)" }, { "__type": "Text", "__tag": 4046, "value": " statement for " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " which is not necessary. Indeed, editing the file above to read" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "and running " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py -c myroutine.pyf myroutine.f90" }, { "__type": "Text", "__tag": 4046, "value": " yields correct results." } ] } ], "title": [ { "__type": "InlineCode", "__tag": 4051, "value": "depends" }, { "__type": "Text", "__tag": 4046, "value": " keyword example" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "Wrapping C codes using f2py" } ], "url": "https://scipy.github.io/old-wiki/pages/Cookbook/f2py_and_NumPy.html", "title": "" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "F2py section on the SciPy Cookbook" } ], "url": "https://scipy-cookbook.readthedocs.io/items/F2Py.html", "title": "" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "\"Interfacing With Other Languages\" section on the SciPy Cookbook." } ], "url": "https://scipy-cookbook.readthedocs.io/items/idx_interfacing_with_other_languages.html", "title": "" } ] } ] } ] }, { "__type": "Target", "__tag": 4061, "label": "NumPy issue tracker" }, { "__type": "Target", "__tag": 4061, "label": "test cases" } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Read more" } ], "level": 1, "target": null } ], "local_refs": [] }