1: /*
  2:     This file should be included in NEW routines that compute the
  3:     differencing parameter for finite difference based matrix-free
  4:     methods.  For example, such routines can compute h for use in
  5:     Jacobian-vector products of the form

  7:                        F(x+ha) - F(x)
  8:           F'(u)a  ~=  ----------------
  9:                             h
 10: */


 15: #include <petscmat.h>         /*I  "petscmat.h"   I*/

 17: /*
 18:     Table of functions that manage the computation and understanding
 19:     of the parameter for finite difference based matrix-free computations
 20: */
 21: struct _MFOps {
 22:   PetscErrorCode (*compute)(MatMFFD,Vec,Vec,PetscScalar *,PetscBool * zeroa);
 23:   PetscErrorCode (*view)(MatMFFD,PetscViewer);
 24:   PetscErrorCode (*destroy)(MatMFFD);
 25:   PetscErrorCode (*setfromoptions)(MatMFFD);
 26: };

 28: struct _p_MatMFFD {    /* context for default matrix-free SNES */
 29:   PETSCHEADER(struct _MFOps);
 30:   Vec              w;                      /* work vector */
 31:   MatNullSpace     sp;                     /* null space context */
 32:   PetscReal        error_rel;              /* square root of relative error in computing function */
 33:   PetscScalar      currenth;               /* last differencing parameter h used */
 34:   PetscScalar      *historyh;              /* history of differencing parameter h */
 35:   PetscInt         ncurrenth,maxcurrenth;
 36:   void             *hctx;
 37:   Mat              mat;                    /* back reference to shell matrix that contains this */
 38:   PetscInt         recomputeperiod;        /* how often the h is recomputed; default to 1 */
 39:   PetscInt         count;                  /* used by recomputeperiod */
 40:   PetscErrorCode   (*checkh)(void*,Vec,Vec,PetscScalar*);
 41:   void             *checkhctx;             /* optional context used by MatMFFDSetCheckh() */

 43:   PetscErrorCode   (*func)(void*,Vec,Vec);  /* function used for matrix free */
 44:   void             *funcctx;                     /* the context for the function */
 45:   Vec              current_f;                    /* location of F(u); used with F(u+h) */
 46:   PetscBool        current_f_allocated;
 47:   Vec              current_u;                    /* location of u; used with F(u+h) */

 49:   PetscErrorCode   (*funci)(void*,PetscInt,Vec,PetscScalar*);  /* Evaluates func_[i]() */
 50:   PetscErrorCode   (*funcisetbase)(void*,Vec);            /* Sets base for future evaluations of func_[i]() */

 52:   PetscScalar      vscale,vshift;              /* diagonal scale and shift by scalars */
 53:   Vec              dlscale,drscale,dshift;              /* diagonal scale and shift by vectors */
 54: };

 56: extern PetscFList MatMFFDList;
 57: extern PetscBool  MatMFFDRegisterAllCalled;

 59: #endif