[petsc-dev] Fortran interface definitions

[Barry Smith]

   Fortran bindings for functions generally consist of two parts:

   * An Fortran interface definition that is contained inside a module.

     - these provide the compile-time type checking of Fortran code that calls PETSc

     - the vast majority of these interfaces are generated automatically.

          + the automatic ones  are stored in  $PETSC_ARCH/ftn/src/MANSEC/* 

          +  The small number of manual ones are put in src/MANSEC/ftn-mod/* 

  * A C stub, which is a C routine that is callable directly from Fortran.

     - most of these stubs are generated automatically, but not ones that, for example, return
        a pointer to an array or functions that have function arguments.

         + the automatic ones for a function defined in src/MANSEC/somedirectory/*.c are
            are put in $PETSC_ARCH/ftn/src/MANSEC/somedirectory/*f.c 

         + the manual ones are to be put in src/MANSEC/somedirectory/ftn-custom/z*f.c


PETSc functions that return pointers to arrays (VecGetArray() for example) generally have
a restore partner (VecRestoreArray()). But others, such as KSPGetConvergenceHistory() do
not need a restore partner in C; but they do need a restore partner in Fortran. Hence we
need to provide both the Fortran interface definition for KSPRestoreConvergenceHistory() 
and the C stub for it manually.

When you need to provide interfaces or stubs manually I suggest first run make fortranbindings 
and check to see if it generates the interfaces and stubs you need. For those it generates (and assuming they
are correct) you don't need to do anything more. For any it does not generate you need to make appropriate
manual versions (generally I find something similar and copy it to get the starting code for the needed manual
interfaces and stubs).

Barry


> On Mar 24, 2025, at 7:07 AM, Martin Diehl <martin.diehl at kuleuven.be> wrote:
> 
> Hello,
> 
> as a preparation for the Google Summer of Code, Tapashree and I started
> to work on https://urldefense.us/v3/__https://gitlab.com/petsc/petsc/-/issues/194__;!!G_uCfscf7eWS!fsu7KTFZDG8gA5i0b_mVGz5mDt-t-_5K-BhWbkxMqImoBxLt1kFuLeDwXhoLxA5wviD6Lv9EnMb-QMQDSARQSA$  (interfaces for
> PetscViewerHDF5Write/ReadAttribute()). Preliminary work is in
> https://urldefense.us/v3/__https://gitlab.com/petsc/petsc/-/commits/MarDiehl/194-add-f90-bindings-for-petscviewerhdf5write-readattribute__;!!G_uCfscf7eWS!fsu7KTFZDG8gA5i0b_mVGz5mDt-t-_5K-BhWbkxMqImoBxLt1kFuLeDwXhoLxA5wviD6Lv9EnMb-QMR_MkUJag$ 
> 
> When working on it, I realized that my understanding how Fortran
> interfaces are defined in PETSc faded, so I would need some
> clarifications on the different components.
> 
> Is our understanding about the content of the ftn-custom folders
> correct: Do they only exist in the repository, C-code for functions
> that are not 1-1 translated to Fortran are defined. This includes for
> example functions having arrays or strings in their arguments.
> 
> What are the purposes of the files in the ftn-mod folders? Some seem to
> combine autogenerated modules (e.g. ksp/ftn-mod/petsckspmod.F90),
> others make overloaded functions available under a common name (e.g.
> sys/ftn-mod/petscviewer.h90). But what is "/ksp/ftn-mod/petscksp.h90"
> doing?
> 
> best regards,
> Martin and Tapashree
> 
> -- 
> KU Leuven
> Department of Computer Science
> Department of Materials Engineering
> Celestijnenlaan 200a
> 3001 Leuven, Belgium
>