Pymol-script-repo:收集的Pymol脚本

.. -*- rest -*- ////////////////////////////////////////////////////////////////////// F2PY Users Guide and Reference Manual ////////////////////////////////////////////////////////////////////// :Author: Pearu Peterson :Contact: pearu@cens.ioc.ee :Web site: http://cens.ioc.ee/projects/f2py2e/ :Date: $Date: 2005/04/02 10:03:26 $ :Revision: $Revision: 1.27 $ .. section-numbering:: .. Contents:: ================ Introduction ================ The purpose of the F2PY_ --*Fortran to Python interface generator*-- project is to provide a connection between Python and Fortran languages. F2PY is a Python_ package (with a command line tool ``f2py`` and a module ``f2py2e``) that facilitates creating/building Python C/API extension modules that make it possible * to call Fortran 77/90/95 external subroutines and Fortran 90/95 module subroutines as well as C functions; * to access Fortran 77 ``COMMON`` blocks and Fortran 90/95 module data, including allocatable arrays from Python. See F2PY_ web site for more information and installation instructions. ====================================== Three ways to wrap - getting started ====================================== Wrapping Fortran or C functions to Python using F2PY consists of the following steps: * Creating the so-called signature file that contains descriptions of wrappers to Fortran or C functions, also called as signatures of the functions. In the case of Fortran routines, F2PY can create initial signature file by scanning Fortran source codes and catching all relevant information needed to create wrapper functions. * Optionally, F2PY created signature files can be edited to optimize wrappers functions, make them "smarter" and more "Pythonic". * F2PY reads a signature file and writes a Python C/API module containing Fortran/C/Python bindings. * F2PY compiles all sources and builds an extension module containing the wrappers. In building extension modules, F2PY uses ``numpy_distutils`` that supports a number of Fortran 77/90/95 compilers, including Gnu, Intel, Sun Fortre, SGI MIPSpro, Absoft, NAG, Compaq etc. compilers. Depending on a particular situation, these steps can be carried out either by just in one command or step-by-step, some steps can be ommited or combined with others. Below I'll describe three typical approaches of using F2PY. The following `example Fortran 77 code`__ will be used for illustration: .. include:: fib1.f :literal: __ fib1.f The quick way ============== The quickest way to wrap the Fortran subroutine ``FIB`` to Python is to run :: f2py -c fib1.f -m fib1 This command builds (see ``-c`` flag, execute ``f2py`` without arguments to see the explanation of command line options) an extension module ``fib1.so`` (see ``-m`` flag) to the current directory. Now, in Python the Fortran subroutine ``FIB`` is accessible via ``fib1.fib``:: >>> import Numeric >>> import fib1 >>> print fib1.fib.__doc__ fib - Function signature: fib(a,[n]) Required arguments: a : input rank-1 array('d') with bounds (n) Optional arguments: n := len(a) input int >>> a=Numeric.zeros(8,'d') >>> fib1.fib(a) >>> print a [ 0. 1. 1. 2. 3. 5. 8. 13.] .. topic:: Comments * Note that F2PY found that the second argument ``n`` is the dimension of the first array argument ``a``. Since by default all arguments are input-only arguments, F2PY concludes that ``n`` can be optional with the default value ``len(a)``. * One can use different values for optional ``n``:: >>> a1=Numeric.zeros(8,'d') >>> fib1.fib(a1,6) >>> print a1 [ 0. 1. 1. 2. 3. 5. 0. 0.] but an exception is raised when it is incompatible with the input array ``a``:: >>> fib1.fib(a,10) fib:n=10 Traceback (most recent call last): File "<stdin>", line 1, in ? fib.error: (len(a)>=n) failed for 1st keyword n >>> This demonstrates one of the useful features in F2PY, that it, F2PY implements basic compatibility checks between related arguments in order to avoid any unexpected crashes. * When a Numeric array, that is Fortran contiguous and has a typecode corresponding to presumed Fortran type, is used as an input array argument, then its C pointer is directly passed to Fortran. Otherwise F2PY makes a contiguous copy (with a proper typecode) of the input array and passes C pointer of the copy to Fortran subroutine. As a result, any possible changes to the (copy of) input array have no effect to the original argument, as demonstrated below:: >>> a=Numeric.ones(8,'i') >>> fib1.fib(a) >>> print a [1 1 1 1 1 1 1 1] Clearly, this is not an expected behaviour. The fact that the above example worked with ``typecode='d'`` is considered accidental. F2PY provides ``intent(inplace)`` attribute that would modify the attributes of an input array so that any changes made by Fortran routine will be effective also in input argument. For example, if one specifies ``intent(inplace) a`` (see below, how), then the example above would read: >>> a=Numeric.ones(8,'i') >>> fib1.fib(a) >>> print a [ 0. 1. 1. 2. 3. 5. 8. 13.] However, the recommended way to get changes made by Fortran subroutine back to python is to use ``intent(out)`` attribute. It is more efficient and a cleaner solution. * The usage of ``fib1.fib`` in Python is very similar to using ``FIB`` in Fortran. However, using *in situ* output arguments in Python indicates a poor style as there is no safety mechanism in Python with respect to wrong argument types. When using Fortran or C, compilers naturally discover any type mismatches during compile time but in Python the types must be checked in runtime. So, using *in situ* output arguments in Python may cause difficult to find bugs, not to mention that the codes will be less readable when all required type checks are implemented. Though the demonstrated way of wrapping Fortran routines to Python is very straightforward, it has several drawbacks (see the comments above). These drawbacks are due to the fact that there is no way that F2PY can determine what is the acctual intention of one or the other argument, is it input or output argument, or both, or something else. So, F2PY conservatively assumes that all arguments are input arguments by default. However, there are ways (see below) how to "teach" F2PY about the true intentions (among other things) of function arguments; and then F2PY is able to generate more Pythonic (more explicit, easier to use, and less error prone) wrappers to Fortran functions. The smart way ============== Let's apply the steps of wrapping Fortran functions to Python one by one. * First, we create a signature file from ``fib1.f`` by running :: f2py fib1.f -m fib2 -h fib1.pyf The signature file is saved to ``fib1.pyf`` (see ``-h`` flag) and its contents is shown below. .. include:: fib1.pyf :literal: * Next, we'll teach F2PY that the argument ``n`` is a input argument (use ``intent(in)`` attribute) and that the result, i.e. the contents of ``a`` after calling Fortran function ``FIB``, should be returned to Python (use ``intent(out)`` attribute). In addition, an array ``a`` should be created dynamically using the size given by the input argument ``n`` (use ``depend(n)`` attribute to indicate dependence relation). The content of a modified version of ``fib1.pyf`` (saved as ``fib2.pyf``) is as follows: .. include:: fib2.pyf :literal: * And finally, we build the extensio