{ "__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:advanced:use_cases", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Advanced F2PY use cases" } ], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "User-defined Python C/API functions can be defined inside signature files using " }, { "__type": "InlineCode", "__tag": 4051, "value": "usercode" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "pymethoddef" }, { "__type": "Text", "__tag": 4046, "value": " statements (they must be used inside the " }, { "__type": "InlineCode", "__tag": 4051, "value": "python module" }, { "__type": "Text", "__tag": 4046, "value": " block). For example, the following signature file " }, { "__type": "InlineCode", "__tag": 4051, "value": "spam.pyf" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "! -" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "- f90 -" } ] }, { "__type": "Text", "__tag": 4046, "value": "- python module spam usercode ''' static char doc_spam_system[] = \"Execute a shell command.\"; static PyObject *spam_system(PyObject *self, PyObject *args) { char *command; int sts;" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "wraps the C library function " }, { "__type": "InlineCode", "__tag": 4051, "value": "system()" }, { "__type": "Text", "__tag": 4046, "value": " " } ] }, { "__type": "Code", "__tag": 4050, "value": "f2py -c spam.pyf", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In Python this can then be used as:" } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Adding user-defined functions to F2PY generated modules" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following example illustrates how to add user-defined variables to a F2PY generated extension module by modifying the dictionary of a F2PY generated module. Consider the following signature file (compiled with " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py -c var.pyf" }, { "__type": "Text", "__tag": 4046, "value": "):" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Notice that the second " }, { "__type": "InlineCode", "__tag": 4051, "value": "usercode" }, { "__type": "Text", "__tag": 4046, "value": " statement must be defined inside an " }, { "__type": "InlineCode", "__tag": 4051, "value": "interface" }, { "__type": "Text", "__tag": 4046, "value": " block and the module dictionary is available through the variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "d" }, { "__type": "Text", "__tag": 4046, "value": " (see " }, { "__type": "InlineCode", "__tag": 4051, "value": "varmodule.c" }, { "__type": "Text", "__tag": 4046, "value": " generated by " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py var.pyf" }, { "__type": "Text", "__tag": 4046, "value": " for additional details)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Usage in Python:" } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Adding user-defined variables" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Currently, F2PY can handle only " }, { "__type": "InlineCode", "__tag": 4051, "value": "(kind=)" }, { "__type": "Text", "__tag": 4046, "value": " declarations where " }, { "__type": "InlineCode", "__tag": 4051, "value": "" }, { "__type": "Text", "__tag": 4046, "value": " is a numeric integer (e.g. 1, 2, 4,...), but not a function call " }, { "__type": "InlineCode", "__tag": 4051, "value": "KIND(..)" }, { "__type": "Text", "__tag": 4046, "value": " or any other expression. F2PY needs to know what would be the corresponding C type and a general solution for that would be too complicated to implement." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "However, F2PY provides a hook to overcome this difficulty, namely, users can define their own to maps. For example, if Fortran 90 code contains " } ] }, { "__type": "Code", "__tag": 4050, "value": "REAL(kind=KIND(0.0D0)) ...", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "then create a mapping file containing a Python dictionary " } ] }, { "__type": "Code", "__tag": 4050, "value": "{'real': {'KIND(0.0D0)': 'double'}}", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "for instance." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Use the " }, { "__type": "InlineCode", "__tag": 4051, "value": "--f2cmap" }, { "__type": "Text", "__tag": 4046, "value": " command-line option to pass the file name to F2PY. By default, F2PY assumes file name is " }, { "__type": "InlineCode", "__tag": 4051, "value": ".f2py_f2cmap" }, { "__type": "Text", "__tag": 4046, "value": " in the current working directory." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "More generally, the f2cmap file must contain a dictionary with items " } ] }, { "__type": "Code", "__tag": 4050, "value": " : {:}", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "that defines mapping between Fortran type " } ] }, { "__type": "Code", "__tag": 4050, "value": "([kind=])", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "and the corresponding . The can be one of the following " } ] }, { "__type": "Code", "__tag": 4050, "value": "double\nfloat\nlong_double\nchar\nsigned_char\nunsigned_char\nshort\nunsigned_short\nint\nlong\nlong_long\nunsigned\ncomplex_float\ncomplex_double\ncomplex_long_double\nstring", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For example, for a Fortran file " }, { "__type": "InlineCode", "__tag": 4051, "value": "func1.f" }, { "__type": "Text", "__tag": 4046, "value": " containing:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In order to convert " }, { "__type": "InlineCode", "__tag": 4051, "value": "int64" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "real64" }, { "__type": "Text", "__tag": 4046, "value": " to valid " }, { "__type": "InlineCode", "__tag": 4051, "value": "C" }, { "__type": "Text", "__tag": 4046, "value": " data types, a " }, { "__type": "InlineCode", "__tag": 4051, "value": ".f2py_f2cmap" }, { "__type": "Text", "__tag": 4046, "value": " file with the following content can be created in the current directory:" } ] }, { "__type": "Code", "__tag": 4050, "value": "dict(real=dict(real64='double'), integer=dict(int64='long long'))", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "and create the module as usual. F2PY checks if a " }, { "__type": "InlineCode", "__tag": 4051, "value": ".f2py_f2cmap" }, { "__type": "Text", "__tag": 4046, "value": " file is present in the current directory and will use it to map " }, { "__type": "InlineCode", "__tag": 4051, "value": "KIND" }, { "__type": "Text", "__tag": 4046, "value": " specifiers to " }, { "__type": "InlineCode", "__tag": 4051, "value": "C" }, { "__type": "Text", "__tag": 4046, "value": " data types." } ] }, { "__type": "Code", "__tag": 4050, "value": "f2py -c func1.f -m func1", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Alternatively, the mapping file can be saved with any other name, for example " }, { "__type": "InlineCode", "__tag": 4051, "value": "mapfile.txt" }, { "__type": "Text", "__tag": 4046, "value": ", and this information can be passed to F2PY by using the " }, { "__type": "InlineCode", "__tag": 4051, "value": "--f2cmap" }, { "__type": "Text", "__tag": 4046, "value": " option." } ] }, { "__type": "Code", "__tag": 4050, "value": "f2py -c func1.f -m func1 --f2cmap mapfile.txt", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For more information, see F2Py source code " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy/f2py/capi_maps.py" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Dealing with KIND specifiers" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Character strings" } ], "level": 1, "target": "Character strings" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In Fortran, assumed length character string arguments are declared as " }, { "__type": "InlineCode", "__tag": 4051, "value": "character*(*)" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "character(len=*)" }, { "__type": "Text", "__tag": 4046, "value": ", that is, the length of such arguments are determined by the actual string arguments at runtime. For " }, { "__type": "InlineCode", "__tag": 4051, "value": "intent(in)" }, { "__type": "Text", "__tag": 4046, "value": " arguments, this lack of length information poses no problems for f2py to construct functional wrapper functions. However, for " }, { "__type": "InlineCode", "__tag": 4051, "value": "intent(out)" }, { "__type": "Text", "__tag": 4046, "value": " arguments, the lack of length information is problematic for f2py generated wrappers because there is no size information available for creating memory buffers for such arguments and F2PY assumes the length is 0. Depending on how the length of assumed length character strings are specified, there exist ways to workaround this problem, as exemplified below." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the length of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "character*(*)" }, { "__type": "Text", "__tag": 4046, "value": " output argument is determined by the state of other input arguments, the required connection can be established in a signature file or within a f2py-comment by adding an extra declaration for the corresponding argument that specifies the length in character selector part. For example, consider a Fortran file " }, { "__type": "InlineCode", "__tag": 4051, "value": "asterisk1.f90" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compile it with " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py -c asterisk1.f90 -m asterisk1" }, { "__type": "Text", "__tag": 4046, "value": " and then in Python:" } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import asterisk1\n>>> asterisk1.foo1()\nb'123456789A12'", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Notice that the extra declaration " }, { "__type": "InlineCode", "__tag": 4051, "value": "character(f2py_len=12) s" }, { "__type": "Text", "__tag": 4046, "value": " is interpreted only by f2py and in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py_len=" }, { "__type": "Text", "__tag": 4046, "value": " specification one can use C-expressions as a length value." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the following example:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "the length of the output assumed length string depends on an input argument " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": ", after wrapping with F2PY, in Python:" } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import asterisk\n>>> asterisk.foo2(2)\nb'12'\n>>> asterisk.foo2(12)\nb'123456789A12'\n>>>", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Assumed length character strings" } ], "level": 2, "target": null } ], "local_refs": [] }