Coverage for pyguymer3/f90/__init__.py: 100%

1#!/usr/bin/env python3 

2 

3""" 

4A Python sub-module containing a bunch of random functions that I have written 

5over the years in FORTRAN to be called from Python using `f2py 

6<https://numpy.org/doc/stable/f2py/>`_. 

7 

8Notes 

9----- 

10* To compile the FORTRAN source code and create the sub-module just run the 

11 Makefile. 

12* `f2py <https://numpy.org/doc/stable/f2py/>`_ isn't good at creating interfaces 

13 to FORTRAN functions, so all the FORTRAN here will be subroutines (see these 

14 Stack Overflow questions [1]_ and [2]_). 

15* `f2py <https://numpy.org/doc/stable/f2py/>`_ doesn't release the GIL, so I 

16 have to do that with a macro (see this StackOverflow question [3]_). 

17 

18Documentation of the FORTRAN subroutine can be obtained by running: 

19 

20>>> import pyguymer3 

21>>> import pyguymer3.f90 

22>>> print(pyguymer3.f90.funcs.${FUNC}.__doc__) 

23 

24According to the definition of ``c2py_map.keys()`` in the `source of 

25"capi_maps.py" 

26<https://github.com/numpy/numpy/blob/master/numpy/f2py/capi_maps.py>`_ 

27(in the `source of "f2py" 

28<https://github.com/numpy/numpy/tree/master/numpy/f2py>`_) only the following 

29short-hands for C data types are recognised by `f2py 

30<https://numpy.org/doc/stable/f2py/>`_: 

31 

32* ``double`` 

33* ``float`` 

34* ``long_double`` 

35* ``char`` 

36* ``signed_char`` 

37* ``unsigned_char`` 

38* ``short`` 

39* ``unsigned_short`` 

40* ``int`` 

41* ``long`` 

42* ``long_long`` 

43* ``unsigned`` 

44* ``complex_float`` 

45* ``complex_double`` 

46* ``complex_long_double`` 

47* ``string`` 

48 

49According to the `gfortran "ISO_C_BINDING" documentation 

50<https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fC_005fBINDING.html>`_ only the 

51following FORTRAN-C mappings are possible (where mappings have been removed if 

52the corresponding C data type does not have a corresponding short-hand in `f2py 

53<https://numpy.org/doc/stable/f2py/>`_ above): 

54 

55* integer 

56 

57 * FORTRAN ``C_INT`` goes to C ``int`` (which is ``int`` in `f2py 

58 <https://numpy.org/doc/stable/f2py/>`_) 

59 * FORTRAN ``C_SHORT`` goes to C ``short int`` (which is ``short`` in `f2py 

60 <https://numpy.org/doc/stable/f2py/>`_) 

61 * FORTRAN ``C_LONG`` goes to C ``long int`` (which is ``long`` in `f2py 

62 <https://numpy.org/doc/stable/f2py/>`_) 

63 * FORTRAN ``C_LONG_LONG`` goes to C ``long long int`` (which is 

64 ``long_long`` in `f2py <https://numpy.org/doc/stable/f2py/>`_) 

65 * FORTRAN ``C_SIGNED_CHAR`` goes to C ``signed char`` (which is 

66 ``signed_char`` in `f2py <https://numpy.org/doc/stable/f2py/>`_) 

67 

68* real 

69 

70 * FORTRAN ``C_FLOAT`` goes to C ``float`` (which is ``float`` in `f2py 

71 <https://numpy.org/doc/stable/f2py/>`_) 

72 * FORTRAN ``C_DOUBLE`` goes to C ``double`` (which is ``double`` in `f2py 

73 <https://numpy.org/doc/stable/f2py/>`_) 

74 * FORTRAN ``C_LONG_DOUBLE`` goes to C ``long double`` (which is 

75 ``long_double`` in `f2py <https://numpy.org/doc/stable/f2py/>`_) 

76 

77* complex 

78 

79 * FORTRAN ``C_FLOAT_COMPLEX`` goes to C ``float _Complex`` (which is 

80 ``complex_float`` in `f2py <https://numpy.org/doc/stable/f2py/>`_) 

81 * FORTRAN ``C_DOUBLE_COMPLEX`` goes to C ``double _Complex`` (which is 

82 ``complex_double`` in `f2py <https://numpy.org/doc/stable/f2py/>`_) 

83 * FORTRAN ``C_LONG_DOUBLE_COMPLEX`` goes to C ``long double _Complex`` ( 

84 which is ``complex_long_double`` in `f2py 

85 <https://numpy.org/doc/stable/f2py/>`_) 

86 

87* character 

88 

89 * FORTRAN ``C_CHAR`` goes to C ``char`` (which is ``char`` in `f2py 

90 <https://numpy.org/doc/stable/f2py/>`_) 

91 

92The above study has led me to create :download:`.f2py_f2cmap 

93<../../pyguymer3/f90/.f2py_f2cmap>` to allow me to use FORTRAN data types from 

94"ISO_C_BINDING" and have them magically mapped over to the *correct* 

95corresponding C data type in `f2py <https://numpy.org/doc/stable/f2py/>`_. 

96 

97Copyright 2017 Thomas Guymer [4]_ 

98 

99References 

100---------- 

101.. [1] "f2py array valued functions" on StackOverflow, https://stackoverflow.com/q/10913003 

102.. [2] "when using f2py, function scope within FORTRAN module different than when compiled for FORTRAN program" on StackOverflow, https://stackoverflow.com/q/18669814 

103.. [3] "f2py function release GIL" on StackOverflow, https://stackoverflow.com/q/15976369 

104.. [4] PyGuymer3, https://github.com/Guymer/PyGuymer3 

105""" 

106 

107# Import sub-functions ... 

108from .funcs import *