1:  #include <petsc/private/linesearchimpl.h>
  2:  #include <petsc/private/snesimpl.h>

  4: typedef struct {
  5:   SNESLineSearchUserFunc func;
  6:   void                   *ctx;
  7: } SNESLineSearch_Shell;

  9: /*@C
 10:    SNESLineSearchShellSetUserFunc - Sets the user function for the SNESLineSearch Shell implementation.

 12:    Not Collective

 14:    Input Parameters:
 15: +  linesearch - SNESLineSearch context
 16: .  func - function implementing the linesearch shell.
 17: -  ctx - context for func

 19:    Calling sequence of func:
 20: +  linesearch - the linesearch instance
 21: -  ctx - the above mentioned context

 23:    Usage:

 25: $  PetscErrorCode shellfunc(SNESLineSearch linesearch,void * ctx)
 26: $  {
 27: $     Vec  X,Y,F,W,G;
 28: $     SNES snes;
 30: $     SNESLineSearchGetSNES(linesearch,&snes);
 31: $     SNESLineSearchSetReason(linesearch,SNES_LINESEARCH_SUCCEEDED);
 32: $     SNESLineSearchGetVecs(linesearch,&X,&F,&Y,&W,&G);
 33: $     .. determine lambda using W and G as work vecs..
 34: $     VecAXPY(X,-lambda,Y);
 35: $     SNESComputeFunction(snes,X,F);
 36: $     SNESLineSearchComputeNorms(linesearch);
 37: $     return(0);
 38: $  }
 39: $
 40: $  ...
 41: $
 42: $  SNESGetLineSearch(snes, &linesearch);
 43: $  SNESLineSearchSetType(linesearch, SNESLINESEARCHSHELL);
 44: $  SNESLineSearchShellSetUserFunc(linesearch, shellfunc, NULL);

 46:    Level: advanced

 48:    .keywords: SNESLineSearch, Shell, user, function, set

 50:    .seealso: SNESLineSearchShellGetUserFunc(), SNESLINESEARCHSHELL
 51: @*/
 52: PetscErrorCode SNESLineSearchShellSetUserFunc(SNESLineSearch linesearch, SNESLineSearchUserFunc func, void *ctx)
 53: {
 54:   PetscErrorCode       ierr;
 55:   PetscBool            flg;
 56:   SNESLineSearch_Shell *shell = (SNESLineSearch_Shell*)linesearch->data;

 60:   PetscObjectTypeCompare((PetscObject)linesearch,SNESLINESEARCHSHELL,&flg);
 61:   if (flg) {
 62:     shell->ctx  = ctx;
 63:     shell->func = func;
 64:   }
 65:   return(0);
 66: }

 68: /*@C
 69:    SNESLineSearchShellGetUserFunc - Gets the user function and context for the shell implementation.

 71:    Not Collective

 73:    Input Parameter:
 74: .     linesearch - the line search object

 76:    Output Parameters:
 77: +    func  - the user function; can be NULL if you do not want it
 78: -    ctx   - the user function context; can be NULL if you do not want it

 80:    Level: advanced

 82:    .keywords: SNESLineSearch, get, Shell, user, function

 84:    .seealso: SNESLineSearchShellSetUserFunc()
 85: @*/
 86: PetscErrorCode SNESLineSearchShellGetUserFunc(SNESLineSearch linesearch, SNESLineSearchUserFunc *func, void **ctx)
 87: {
 88:   PetscErrorCode       ierr;
 89:   PetscBool            flg;
 90:   SNESLineSearch_Shell *shell = (SNESLineSearch_Shell*)linesearch->data;

 96:   PetscObjectTypeCompare((PetscObject)linesearch,SNESLINESEARCHSHELL,&flg);
 97:   if (flg) {
 98:     if (func) *func = shell->func;
 99:     if (ctx) *ctx  = shell->ctx;
100:   }
101:   return(0);
102: }

104: static PetscErrorCode  SNESLineSearchApply_Shell(SNESLineSearch linesearch)
105: {
106:   SNESLineSearch_Shell *shell = (SNESLineSearch_Shell*)linesearch->data;
107:   PetscErrorCode       ierr;

110:   /* apply the user function */
111:   if (shell->func) {
112:     (*shell->func)(linesearch, shell->ctx);
113:   } else SETERRQ(PetscObjectComm((PetscObject)linesearch), PETSC_ERR_USER, "SNESLineSearchShell needs to have a shell function set with SNESLineSearchShellSetUserFunc");
114:   return(0);
115: }

117: static PetscErrorCode  SNESLineSearchDestroy_Shell(SNESLineSearch linesearch)
118: {
119:   SNESLineSearch_Shell *shell = (SNESLineSearch_Shell*)linesearch->data;
120:   PetscErrorCode       ierr;

123:   PetscFree(shell);
124:   return(0);
125: }

127: /*MC
128:    SNESLINESEARCHSHELL - Provides context for a user-provided line search routine.

130: The user routine has one argument, the SNESLineSearch context.  The user uses the interface to
131: extract line search parameters and set them accordingly when the computation is finished.

133: Any of the other line searches may serve as a guide to how this is to be done.  There is also a basic
134: template in the documentation for SNESLineSearchShellSetUserFunc().

136: Level: advanced

138: M*/
139: PETSC_EXTERN PetscErrorCode SNESLineSearchCreate_Shell(SNESLineSearch linesearch)
140: {

142:   SNESLineSearch_Shell *shell;
143:   PetscErrorCode       ierr;

146:   linesearch->ops->apply          = SNESLineSearchApply_Shell;
147:   linesearch->ops->destroy        = SNESLineSearchDestroy_Shell;
148:   linesearch->ops->setfromoptions = NULL;
149:   linesearch->ops->reset          = NULL;
150:   linesearch->ops->view           = NULL;
151:   linesearch->ops->setup          = NULL;

153:   PetscNewLog(linesearch,&shell);

155:   linesearch->data = (void*) shell;
156:   return(0);
157: }