[petsc-dev] Changes to PETSc API for solvers

[Barry Smith]

    Soon I will be pushing an update to master and next changes to KSPSetOperators(), SNESSetJacobian() and TSSetRHS/IJacobian() interfaces.

1)    The MatStructure argument to KSPSetOperators() and the Jacobian computation routines passed to SNESSetJacobian() and TSSetRHS/IJacobian() is now removed. 

       For example KSPSetOperators(ksp,J,B,MatStructure str) is now KSPSetOperators(ksp,J,B)

       Now if you change the operator B KSP will automatically update the preconditioner for the next linear solve and use it and also keeps track of whether the nonzero pattern has changed. If you wish to change the operator but not update the preconditioner use KSPSetReusePrecondition() or the preconditioning lagging options to SNES.

2)   The ComputeJacobian(), ComputeRHS/IJacobian() functions provided to SNESSetJacobian() and TSSetRHS/IJacobian() now have arguments of Mat instead of Mat*.

       For example ComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*) is now ComputeJacobian(SNES,Vec,Mat,Mat);

    History:   1) When KSPSetOperators() was originally written we did not yet have fully developed the concept of PetscObjectState() so we had no way of knowing if the operators mat and pmat had changed and hence maybe the preconditioner should be updated. Hence the MatStructure flag was used in KSP/PCSetOperators() and SNESSetJacobian and TSSetXJacobian. 
     With PetscObjectState() applied to the Pmat and the (newly added in branch barry/mat-nonzero-structure-state) MatGetNonzeroState() it is now possible for the PC to know automatically if the operator or nonzero structure has changed. Thus, the user does not need to track if the matrix values changed or if the nonzero structure changed.
    2) When the arguments to the compute Jacobian routines were Mat* instead of Mat we did not yet have a Mat object whose type could be changed/set reset at any time, thus I provided a way for users to change the actual Mat object by passing Mat* but that feature is no longer needed.

   Why the change: The current interface was cumbersome and getting in the way of implementing very flexible composible preconditioners and nonlinear solvers, this change will simplify those routines and allow us to make make more composible solvers.

   Thanks for your patience with accepting our API changes. We realize it is sometimes painful to update application codes to the new interfaces. Keep in mind that I had to update all of the PETSc code to the new interface so I know your pain :-)

    If the changes pass all the nightly tests tonight I will likely push these changes to master and next on Wednesday.


   Barry