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
