new build system

[Richard Tran Mills]

Folks,

I agree with Leif and Stephan that the API changes between sub-sub-versions of 
PETSc can be a headache.  That said, I almost always LIKE the API changes 
because they usually are more intuitive, consistent, etc.

I work on a Fortran code for groundwater simulation that is built on PETSc. 
To allow the code to build with some different versions of PETSc, we have 
introduced some wrappers.  Our source code tracks PETSc-dev, but to make it 
compatible with "release" versions (the example below is for 2.3.2) we do the 
following.  We have an include file (included by all of our source files) that 
contains

-----
#if (PETSC_VERSION_RELEASE == 1 && PETSC_VERSION_SUBMINOR < 3)

! Name differences between petsc-dev and petsc-release.
#define SNESMonitorSet SNESSetMonitor
#define MatCreateMFFD MatCreateSNESMF
#define MatMFFDSetType MatSNESMFSetType
#define MATMFFD_WP MATSNESMF_WP
#define MatMFFDGetH MatSNESMFGetH
#define MatMFFDSetHHistory MatSNESMFSetHHistory
#define IS_COLORING_GLOBAL IS_COLORING_LOCAL

! Wrappers to handle prototype differences between petsc-dev and petsc-release.
#define VecScatterBegin VecScatterBegin_wrap
#define VecScatterEnd VecScatterEnd_wrap

#endif
-----

And then to handle the prototype differences we have a module that looks like

-----
module PetscRelWrappers
   private

   public :: VecScatterBegin_wrap, VecScatterEnd_wrap

#include "include/finclude/petsc.h"
#include "include/finclude/petscvec.h"
#include "include/finclude/petscvec.h90"

#if (PETSC_VERSION_RELEASE == 1 && PETSC_VERSION_SUBMINOR < 3)

contains

subroutine VecScatterBegin_wrap(inctx,x,y,addv,mode,ierr)
   implicit none

   VecScatter, intent(in) :: inctx
   Vec, intent(in) :: x
   Vec, intent(out) :: y
   InsertMode, intent(in) :: addv
   ScatterMode, intent(in) :: mode
   PetscErrorCode, intent(out) :: ierr

   call VecScatterBegin(x,y,addv,mode,inctx,ierr)
end subroutine VecScatterBegin_wrap


subroutine VecScatterEnd_wrap(inctx,x,y,addv,mode,ierr)
   implicit none

   VecScatter, intent(in) :: inctx
   Vec, intent(in) :: x
   Vec, intent(out) :: y
   InsertMode, intent(in) :: addv
   ScatterMode, intent(in) :: mode
   PetscErrorCode, intent(out) :: ierr

   call VecScatterEnd(x,y,addv,mode,inctx,ierr)
end subroutine VecScatterEnd_wrap

#endif

end module PetscRelWrappers
-----

This allows our code to compile fine with PETSc 2.3.2 even though internally 
our code uses the 2.3.3 (petsc-dev, actually) interfaces.  It would also be 
easy to do the same sort of thing to allow code that uses the 2.3.2 interfaces 
to compile with 2.3.3.

It might be a good idea to have some officially maintained wrappers like this 
(wrapping "older" PETSc interfaces to the new ones), although that might get a 
little messy (maybe more than a little).

I always insist on upgrading code to use the latest PETSc, but I know that 
there are people who either don't care to do this or who simple cannot due to 
circumstances beyond their control.  Folks installed PETSc from a package are 
probably not going to want to have to do this.

Best regards,
Richard Mills

Leif Strand wrote:
> Stephan Kramer wrote:
>> In that respect a related question: is it really necessary to have
>> incompatible changes between sub-sub-versions of PETSc? Most software
>> only makes backwards-incompatible changes when bumping their mayor
>> version number. I must say that I was not really amused when I found out
>> our software would not build with PETSc 2.3.3, because of various small
>> namechanges, such as KSPSetMonitor -> KSPMonitorSet.
> 
> 
> I second all of this. This is a much bigger issue than build system, 
> directory layout, etc. As a library maintainer, one needs religion about 
> this sort of thing. I would expect any library not to make gratuitous 
> changes to the API from one update to the next, and to have a sane 
> version numbering scheme.
> 
> So the number of changes between PETSc 2.3.2 and 2.3.3 was a bit 
> surprising. Given that it adds new features (Sieve), one could argue 
> that it should have been called PETSc 2.4. Given the number of 
> incompatibility-inducing changes (order-of-args for 
> VecScatter{Begin,End}, KSPDefaultSMonitor -> KSPMonitorDefault, etc.) I 
> would argue it should have been called PETSc 3.0. If you're really 
> ambitious, you could implement a separate API layer, and applications 
> can choose which API version they want to use (using a #define, for 
> example). Otherwise, branch management is a must.

-- 
Richard Tran Mills, Ph.D.
Computational Scientist                     E-mail: rmills at ornl.gov
Computational Earth Sciences Group          Phone:  (865) 241-3198
Oak Ridge National Laboratory               Fax:    (865) 574-0405