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*/
 16: #include <petsc/private/petscimpl.h>

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

 29: struct _p_MatMFFD {    /* context for default matrix-free SNES */
 30:   PETSCHEADER(struct _MFOps);
 31:   Vec            w;                        /* work vector */
 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:   void        *ctx;   /* this is used by MatCreateSNESMF() to store the SNES object */
 55: };

 57: PETSC_EXTERN PetscFunctionList MatMFFDList;
 58: PETSC_EXTERN PetscBool         MatMFFDRegisterAllCalled;
 59: PETSC_EXTERN PetscErrorCode    MatMFFDRegisterAll(void);

 61: #endif