[Matrix-SIG] Fortran-to-python-interface-generator: looking for opinions

[Pearu Peterson]

Travis and others interested in the subject,

I am in a process of rewriting the fortran (in future, also C) to python
interface generator (f2py.py) and I am looking for opinions on the
following question:
How the Python user should see the interfaced fortran routine?
I will be more specific in below:

** Consider the interface of fortran (77,90) subroutine `sub`:
subroutine sub(a,b,c,t)
  integer intent(in) :: a
  integer intent(out) :: b
  integer intent(inout) :: c
  integer intent(temporary) :: t
end subroutine sub
where argument `a` is considered as an input parameter, `b` is a result of
`sub`, `c` is both input and output parameter, and `t` is a temporary
(work space) variable (this is quite common in fortran 77 routines when
work space is required for the routine).

** Now say that the interface generator generates (and compiles)
Py/C API module `test` containing function `sub`. As I see it, there
are at least three possible ways to call `sub` and interpret its
arguments and results:

1) test.sub(a,b,c,t) --- that is in python `sub` has similar definition as
in Fortran. This is advantage if interfacing automatically large fortran
libraries like lapack and others: almost no need to write documentation as
it is available for fortran routines. Disadvantage is that in this case
all out and inout arguments must be Numeric arrays, even for scalars and
this might be confusing. Also, the user must supply the work-space
variable `t`, though for the end python user it should be irrelevant.

2) test.sub(a,b,c) --- this is a kind of reduced form of 1): no work-space
variable in argument list (the work space is allocated automatically in
the Py/C API interface). There are fortran routines that take, say, 20
arguments, and say, half of them, are work-space variables. So, for these
cases reducing the number of arguments may seem to be an advantage, but
the user may be even more confused if in/out/inout/temporary arguments for
fortran routine are mixed, and as a result, the fortran documentation does
not hold for interfaced python function.
Disadvantage of hiding workspace variables is that they are
allocated/disallocated in each call to function which is not good for
performance.

3) b,c=test.sub(a,b) --- here all output of `sub` is returned by the
functions `sub` as a tuple. The advantage of this approach is that here it
is much clearer which arguments are input and which output. As an
disadvantage, the fortran documentation does not hold.


Above I have pointed out that in cases 2) and 3) the fortran
documentations will not hold and I have considered this as a
disadvantage. But is this an argument for python user who is also novice
in fortran? 
Another point is that if making an interface to some fortran library, the
end user needs not to specify all the arguments that fortran routine
initially has: there should be (almost always) a higher level interface
written in python that deals with, say, specifying arguments (to fortran
routine) representing the length of vectors and so reducing the number of
arguments in python.
In conclusion, interfaced fortran routines need python specific
documentation anyway. That's why I have proposed options 2) and 3).

Any thoughts, suggestions are very welcome as I need to decide in which
direction I should proceed. All given ways are possible in terms of
optional flags, but which way should be default?  

With regards,
	Pearu