Update to PETSc Fortran interfaces

[Barry Smith]

  I have pushed a set of updates to the PETSc Fortran interfaces. To  
compile with these you
should do a rm -rf exernalpackages/sowing* $PETSC_ARCH/conf/sowing  
then rerun config/configure.py
If you do not wish to experiment with the new features you do not need  
to do this.

  For most users of PETSc from Fortran this need not change anything  
at all and you
can continue to use PETSc as always.

  If you config/configure.py with the additional option --with-fortran- 
interfaces then Bill Gropp's
sowing package will automatically generate Fortran interface  
definitions for all the PETSc functions.
You can utilize these interfaces (for type checking of arguments to  
function calls) simply include
in each Fortran subroutine you write
#include "finclude/petscvec.h90" etc after the
#include "finclude/petscvec.h" etc you currently use.

  It is also now much easier to use PETSc Fortran modules. I've  
attached the new manual
page for UsingFortran below. I don't particularly recommend using the  
Fortran modules
instead of the #include "finclude/petscvec.h90" etc. They both provide  
the same functionality
(argument type checking) the modules are just for people who "prefer"  
doing things
in a more "Fortran way."

   Please report any build problems etc to petsc-maint at mcs.anl.gov

   Barry


    UsingFortran - Fortran can be used with PETSc in four distinct  
approaches

$    1) classic Fortran 77 style
$#include "petscXXX.h" to work with material from the XXX component of  
PETSc
$       XXX variablename
$      You cannot use this approach if you wish to use the Fortran 90  
specific PETSc routines
$      which end in F90; such as VecGetArrayF90()
$
$    2) classic Fortran 90 style
$#include "petscXXX.h"
$#include "petscXXX.h90" to work with material from the XXX component  
of PETSc
$       XXX variablename
$
$    3) Using Fortran modules
$#include "petscXXXdef.h"
$         use petscXXXX
$       XXX variablename
$
$    4) Use Fortran modules and Fortran data types for PETSc types
$#include "petscXXXdef.h"
$         use petscXXXX
$       type(XXX) variablename
$      To use this approach you must config/configure.py PETSc with  
the additional
$      option --with-fortran-datatypes You cannot use the type(XXX)  
declaration approach without using Fortran modules

    Finally if you absolutely do not want to use any #include you can  
use either

$    3a) skip the #include BUT you cannot use any PETSc data type  
names like Vec, Mat, PetscInt, PetscErrorCode etc
$        and you must declare the variables as integer, for example
$        integer variablename
$
$    4a) skip the #include, you use the object types like type(Vec)  
type(Mat) but cannot use the data type
$        names like PetscErrorCode, PetscInt etc. again for those you  
must use integer

   We recommend either 2 or 3. Approaches 2 and 3 provide type  
checking for most PETSc function calls; 4 has type checking
for only a few PETSc functions.

   Fortran type checking with interfaces is strick, this means you  
cannot pass a scalar value when an array value
is expected (even though it is legal Fortran). For example when  
setting a single value in a matrix with MatSetValues()
you cannot have something like
$      PetscInt row,col
$      PetscScalar val
$        ...
$      call MatSetValues(mat,1,row,1,col,val,INSERT_VALUES,ierr)
You must instead have
$      PetscInt row(1),col(1)
$      PetscScalar val(1)
$        ...
$      call MatSetValues(mat,1,row,1,col,val,INSERT_VALUES,ierr)


    See the example src/vec/vec/examples/tutorials/ex20f90.F90 for an  
example that can use all four approaches

    Developer Notes: The finclude/petscXXXdef.h contain all the  
#defines (would be typedefs in C code) these
     automatically include their predecessors; for example finclude/ 
petscvecdef.h includes finclude/petscisdef.h

     The finclude/petscXXXX.h contain all the parameter statements for  
that package. These automatically include
     their finclude/petscXXXdef.h file but DO NOT automatically  
include their predecessors;  for example
     finclude/petscvec.h does NOT automatically include finclude/ 
petscis.h

     The finclude/ftn-custom/petscXXXdef.h90 are not intended to be  
used directly in code, they define the
     Fortran data type type(XXX) (for example type(Vec)) when PETSc is  
config/configure.py with the --with-fortran-datatypes option.

     The finclude/ftn-custom/petscXXX.h90 (not included directly by  
code) contain interface definitions for
     the PETSc Fortran stubs that have different bindings then their C  
version (for example VecGetArrayF90).

     The finclude/ftn-auto/petscXXX.h90 (not included directly by  
code) contain interface definitions generated
     automatically by "make allfortranstubs".

     The finclude/petscXXX.h90 includes the custom finclude/ftn-custom/ 
petscXXX.h90 and if config/configure.py
     was run with --with-fortran-interfaces it also includes the  
finclude/ftn-auto/petscXXX.h90 These DO NOT automatically
     include their predecessors

    Level: beginner