Actual source code: linesearchshell.c

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

 44:    Level: advanced

 46: .seealso: `SNESLineSearchShellGetUserFunc()`, `SNESLINESEARCHSHELL`, `SNESLineSearchType`, `SNESLineSearch`
 47: @*/
 48: PetscErrorCode SNESLineSearchShellSetUserFunc(SNESLineSearch linesearch, SNESLineSearchUserFunc func, void *ctx)
 49: {
 50:   PetscBool             flg;
 51:   SNESLineSearch_Shell *shell = (SNESLineSearch_Shell *)linesearch->data;

 54:   PetscObjectTypeCompare((PetscObject)linesearch, SNESLINESEARCHSHELL, &flg);
 55:   if (flg) {
 56:     shell->ctx  = ctx;
 57:     shell->func = func;
 58:   }
 59:   return 0;
 60: }

 62: /*@C
 63:    SNESLineSearchShellGetUserFunc - Gets the user function and context for the  `SNESLINESEARCHSHELL`

 65:    Not Collective

 67:    Input Parameter:
 68: .   linesearch - the line search object

 70:    Output Parameters:
 71: +    func  - the user function; can be NULL if you do not want it
 72: -    ctx   - the user function context; can be NULL if you do not want it

 74:    Level: advanced

 76: .seealso: `SNESLineSearchShellSetUserFunc()`, `SNESLINESEARCHSHELL`, `SNESLineSearchType`, `SNESLineSearch`
 77: @*/
 78: PetscErrorCode SNESLineSearchShellGetUserFunc(SNESLineSearch linesearch, SNESLineSearchUserFunc *func, void **ctx)
 79: {
 80:   PetscBool             flg;
 81:   SNESLineSearch_Shell *shell = (SNESLineSearch_Shell *)linesearch->data;

 86:   PetscObjectTypeCompare((PetscObject)linesearch, SNESLINESEARCHSHELL, &flg);
 87:   if (flg) {
 88:     if (func) *func = shell->func;
 89:     if (ctx) *ctx = shell->ctx;
 90:   }
 91:   return 0;
 92: }

 94: static PetscErrorCode SNESLineSearchApply_Shell(SNESLineSearch linesearch)
 95: {
 96:   SNESLineSearch_Shell *shell = (SNESLineSearch_Shell *)linesearch->data;

 98:   /* apply the user function */
 99:   if (shell->func) {
100:     (*shell->func)(linesearch, shell->ctx);
101:   } else SETERRQ(PetscObjectComm((PetscObject)linesearch), PETSC_ERR_USER, "SNESLineSearchShell needs to have a shell function set with SNESLineSearchShellSetUserFunc");
102:   return 0;
103: }

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

109:   PetscFree(shell);
110:   return 0;
111: }

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

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

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

122: Level: advanced

124: .seealso: `SNESLineSearch`, `SNES`, `SNESLineSearchCreate()`, `SNESLineSearchSetType()`
125: M*/
126: PETSC_EXTERN PetscErrorCode SNESLineSearchCreate_Shell(SNESLineSearch linesearch)
127: {
128:   SNESLineSearch_Shell *shell;

130:   linesearch->ops->apply          = SNESLineSearchApply_Shell;
131:   linesearch->ops->destroy        = SNESLineSearchDestroy_Shell;
132:   linesearch->ops->setfromoptions = NULL;
133:   linesearch->ops->reset          = NULL;
134:   linesearch->ops->view           = NULL;
135:   linesearch->ops->setup          = NULL;

137:   PetscNew(&shell);

139:   linesearch->data = (void *)shell;
140:   return 0;
141: }