Commits

BarryFSmith committed 0a36f54 Merge

Merge branch 'barry/improve-linesearch-docs' into next

  • Participants
  • Parent commits 6583d69, f190f2f
  • Branches knepley/fix-quadrature-order, next-oct-2014

Comments (0)

Files changed (2)

include/petscsnes.h

 
 /* set the functions for precheck and postcheck */
 
-PETSC_EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNESLineSearch, PetscErrorCode (*SNESLineSearchPreCheckFunction)(SNESLineSearch,Vec,Vec,PetscBool*,void*), void *ctx);
-PETSC_EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNESLineSearch, PetscErrorCode (*SNESLineSearchPostCheckFunction)(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *,void*), void *ctx);
+PETSC_EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch,Vec,Vec,PetscBool*,void*), void *ctx);
+PETSC_EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *,void*), void *ctx);
 
-PETSC_EXTERN PetscErrorCode SNESLineSearchGetPreCheck(SNESLineSearch, PetscErrorCode (**SNESLineSearchPreCheckFunction)(SNESLineSearch,Vec,Vec,PetscBool*,void*), void **ctx);
-PETSC_EXTERN PetscErrorCode SNESLineSearchGetPostCheck(SNESLineSearch, PetscErrorCode (**SNESLineSearchPostCheckFunction)(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *,void*), void **ctx);
+PETSC_EXTERN PetscErrorCode SNESLineSearchGetPreCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch,Vec,Vec,PetscBool*,void*), void **ctx);
+PETSC_EXTERN PetscErrorCode SNESLineSearchGetPostCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *,void*), void **ctx);
 
 /* set the functions for VI-specific line search operations */
 

src/snes/linesearch/interface/linesearch.c

 .  linesearch - The LineSearch instance.
 
    Notes:
-   For most cases, this needn't be called outside of SNESLineSearchApply().
+   For most cases, this needn't be called by users or outside of SNESLineSearchApply().
    The only current case where this is called outside of this is for the VI
    solvers, which modify the solution and work vectors before the first call
    of SNESLineSearchApply, requiring the SNESLineSearch work vectors to be
 #define __FUNCT__ "SNESLineSearchReset"
 
 /*@
-   SNESLineSearchReset - Undoes the SetUp and deletes any Vecs or Mats allocated by the line search.
+   SNESLineSearchReset - Undoes the SNESLineSearchSetUp() and deletes any Vecs or Mats allocated by the line search.
 
    Collective on SNESLineSearch
 
    Input Parameters:
 .  linesearch - The LineSearch instance.
 
-   Level: intermediate
+   Notes: Usually only called by SNESReset()
+
+   Level: developer
 
 .keywords: SNESLineSearch, Reset
 
 #undef __FUNCT__
 #define __FUNCT__ "SNESLineSearchSetFunction"
 /*@C
-   SNESLineSearchSetPreCheck - Sets the function evaluation context on the
+   SNESLineSearchSetFunction - Sets the function evaluation used by the SNES line search
 
    Input Parameters:
 .  linesearch - the SNESLineSearch context
-
-   Output Parameters:
-+  func       - [optional] function evaluation routine
++  func       - function evaluation routine
 
    Level: developer
 
+   Notes: This is used internally by PETSc and not called by users
+
 .keywords: get, linesearch, pre-check
 
-.seealso: SNESLineSearchGetPostCheck(), SNESLineSearchSetPreCheck()
+.seealso: SNESSetFunction()
 @*/
 PetscErrorCode  SNESLineSearchSetFunction(SNESLineSearch linesearch, PetscErrorCode (*func)(SNES,Vec,Vec))
 {
 
 
 /*MC
-    SNESLineSearchPreCheckFunction - functional form passed to check before line search is called
+    SNESLineSearchPreCheckFunction - form of function passed to check the search direction before line search is called
 
      Synopsis:
      #include <petscsnes.h>
 .      y - search direction vector
 -      changed - flag to indicate the precheck changed x or y.
 
+     Note: This is NOTE a PETSc function, rather it documents the calling sequence of functions passed to SNESLineSearchSetPreCheck()
+           and SNESLineSearchGetPreCheck()
+
    Level: advanced
 
-.seealso:   SNESLineSearchSetPreCheck(), SNESLineSearchSetPostCheck()
+.seealso:   SNESLineSearchSetPreCheck(), SNESLineSearchGetPreCheck(), SNESLineSearchSetPostCheck(), SNESLineSearchGetPostCheck() 
 M*/
 
 #undef __FUNCT__
 #define __FUNCT__ "SNESLineSearchSetPreCheck"
 /*@C
-   SNESLineSearchSetPreCheck - Sets a pre-check function for the line search routine.
+   SNESLineSearchSetPreCheck - Sets a user function that is called after the initial search direction has been computed but 
+         before the the line search routine has been applied. Allows the user to adjust the result of (usually a linear solve) that
+         determined the search direction.
 
    Logically Collective on SNESLineSearch
 
    Input Parameters:
 +  linesearch - the SNESLineSearch context
-.  SNESLineSearchPreCheckFunction - [optional] function evaluation routine
--  ctx        - [optional] user-defined context for private data for the
-                function evaluation routine (may be NULL)
-
+.  func - [optional] function evaluation routine, see SNESLineSearchPreCheckFunction for the calling sequence
+-  ctx        - [optional] user-defined context for private data for the function evaluation routine (may be NULL)
 
    Level: intermediate
 
 .keywords: set, linesearch, pre-check
 
-.seealso: SNESLineSearchSetPostCheck()
+.seealso: SNESLineSearchSetPostCheck(), SNESLineSearchGetPostCheck(), SNESLineSearchGetPreCheck()
 @*/
-PetscErrorCode  SNESLineSearchSetPreCheck(SNESLineSearch linesearch, PetscErrorCode (*SNESLineSearchPreCheckFunction)(SNESLineSearch,Vec,Vec,PetscBool*,void*),void *ctx)
+PetscErrorCode  SNESLineSearchSetPreCheck(SNESLineSearch linesearch, PetscErrorCode (*func)(SNESLineSearch,Vec,Vec,PetscBool*,void*),void *ctx)
 {
   PetscFunctionBegin;
   PetscValidHeaderSpecific(linesearch,SNESLINESEARCH_CLASSID,1);
-  if (SNESLineSearchPreCheckFunction) linesearch->ops->precheck = SNESLineSearchPreCheckFunction;
+  if (func) linesearch->ops->precheck = func;
   if (ctx) linesearch->precheckctx = ctx;
   PetscFunctionReturn(0);
 }
 .  linesearch - the SNESLineSearch context
 
    Output Parameters:
-+  func       - [optional] function evaluation routine
--  ctx        - [optional] user-defined context for private data for the
-                function evaluation routine (may be NULL)
++  func       - [optional] function evaluation routine, see SNESLineSearchPreCheckFunction for calling sequence
+-  ctx        - [optional] user-defined context for private data for the function evaluation routine (may be NULL)
 
    Level: intermediate
 
 
 .seealso: SNESLineSearchGetPostCheck(), SNESLineSearchSetPreCheck()
 @*/
-PetscErrorCode  SNESLineSearchGetPreCheck(SNESLineSearch linesearch, PetscErrorCode (**SNESLineSearchPreCheckFunction)(SNESLineSearch,Vec,Vec,PetscBool*,void*),void **ctx)
+PetscErrorCode  SNESLineSearchGetPreCheck(SNESLineSearch linesearch, PetscErrorCode (**func)(SNESLineSearch,Vec,Vec,PetscBool*,void*),void **ctx)
 {
   PetscFunctionBegin;
   PetscValidHeaderSpecific(linesearch,SNESLINESEARCH_CLASSID,1);
-  if (SNESLineSearchPreCheckFunction) *SNESLineSearchPreCheckFunction = linesearch->ops->precheck;
+  if (func) *func = linesearch->ops->precheck;
   if (ctx) *ctx = linesearch->precheckctx;
   PetscFunctionReturn(0);
 }
 
 /*MC
-    SNESLineSearchPostheckFunction - functional form that is called after line search is complete
+    SNESLineSearchPostCheckFunction - form of function that is called after line search is complete
 
      Synopsis:
      #include <petscsnes.h>
 .      changed_y - indicates that the line search changed y
 -      changed_w - indicates that the line search changed w
 
+     Note: This is NOTE a PETSc function, rather it documents the calling sequence of functions passed to SNESLineSearchSetPostCheck()
+           and SNESLineSearchGetPostCheck()
+
    Level: advanced
 
-.seealso:   SNESLineSearchSetPreCheck(), SNESLineSearchSetPostCheck()
+.seealso:   SNESLineSearchSetPreCheck(), SNESLineSearchSetPostCheck(), SNESLineSearchGetPreCheck(), SNESLineSearchGetPostCheck()
 M*/
 
 #undef __FUNCT__
 #define __FUNCT__ "SNESLineSearchSetPostCheck"
 /*@C
-   SNESLineSearchSetPostCheck - Sets a post-check function for the line search routine.
+   SNESLineSearchSetPostCheck - Sets a user function that is called after the line search has been applied to determine the step
+       direction and length. Allows the user a chance to change or override the decision of the line search routine
 
    Logically Collective on SNESLineSearch
 
    Input Parameters:
 +  linesearch - the SNESLineSearch context
-.  SNESLineSearchPostCheckFunction - [optional] function evaluation routine
--  ctx        - [optional] user-defined context for private data for the
-                function evaluation routine (may be NULL)
+.  func - [optional] function evaluation routine, see SNESLineSearchPostCheckFunction for the calling sequence
+-  ctx        - [optional] user-defined context for private data for the function evaluation routine (may be NULL)
 
    Level: intermediate
 
 
 .seealso: SNESLineSearchSetPreCheck()
 @*/
-PetscErrorCode  SNESLineSearchSetPostCheck(SNESLineSearch linesearch, PetscErrorCode (*SNESLineSearchPostCheckFunction)(SNESLineSearch,Vec,Vec,Vec,PetscBool*,PetscBool*,void*),void *ctx)
+PetscErrorCode  SNESLineSearchSetPostCheck(SNESLineSearch linesearch, PetscErrorCode (*func)(SNESLineSearch,Vec,Vec,Vec,PetscBool*,PetscBool*,void*),void *ctx)
 {
   PetscFunctionBegin;
   PetscValidHeaderSpecific(linesearch,SNESLINESEARCH_CLASSID,1);
-  if (SNESLineSearchPostCheckFunction) linesearch->ops->postcheck = SNESLineSearchPostCheckFunction;
+  if (func) linesearch->ops->postcheck = func;
   if (ctx) linesearch->postcheckctx = ctx;
   PetscFunctionReturn(0);
 }
 .  linesearch - the SNESLineSearch context
 
    Output Parameters:
-+  SNESLineSearchPostCheckFunction - [optional] function evaluation routine
--  ctx        - [optional] user-defined context for private data for the
-                function evaluation routine (may be NULL)
++  func - [optional] function evaluation routine, see for the calling sequence SNESLineSearchPostCheckFunction
+-  ctx        - [optional] user-defined context for private data for the function evaluation routine (may be NULL)
 
    Level: intermediate
 
 
 .seealso: SNESLineSearchGetPreCheck(), SNESLineSearchSetPostCheck()
 @*/
-PetscErrorCode  SNESLineSearchGetPostCheck(SNESLineSearch linesearch, PetscErrorCode (**SNESLineSearchPostCheckFunction)(SNESLineSearch,Vec,Vec,Vec,PetscBool*,PetscBool*,void*),void **ctx)
+PetscErrorCode  SNESLineSearchGetPostCheck(SNESLineSearch linesearch, PetscErrorCode (**func)(SNESLineSearch,Vec,Vec,Vec,PetscBool*,PetscBool*,void*),void **ctx)
 {
   PetscFunctionBegin;
   PetscValidHeaderSpecific(linesearch,SNESLINESEARCH_CLASSID,1);
-  if (SNESLineSearchPostCheckFunction) *SNESLineSearchPostCheckFunction = linesearch->ops->postcheck;
+  if (func) *func = linesearch->ops->postcheck;
   if (ctx) *ctx = linesearch->postcheckctx;
   PetscFunctionReturn(0);
 }
    Output Parameters:
 .  changed - Indicator that the precheck routine has changed anything
 
-   Level: Beginner
+   Level: developer
 
 .keywords: SNESLineSearch, Create
 
 +  changed_Y - Indicator if the direction Y has been changed.
 -  changed_W - Indicator if the new candidate solution W has been changed.
 
-   Level: Intermediate
+   Level: developer
 
 .keywords: SNESLineSearch, Create
 
 
    Level: intermediate
 
-
 .seealso: SNESLineSearchGetMonitor(), PetscViewer
 @*/
 PetscErrorCode  SNESLineSearchSetMonitor(SNESLineSearch linesearch, PetscBool flg)
 /*@
    SNESLineSearchGetMonitor - Gets the PetscViewer instance for the line search monitor.
 
-   Input Parameters:
+   Input Parameter:
 .  linesearch - linesearch context
 
-   Input Parameters:
+   Output Parameter:
 .  monitor - monitor context
 
    Logically Collective on SNES
 
-
    Options Database Keys:
 .   -snes_linesearch_monitor - enables the monitor
 
    Level: intermediate
 
-
 .seealso: SNESLineSearchSetMonitor(), PetscViewer
 @*/
 PetscErrorCode  SNESLineSearchGetMonitor(SNESLineSearch linesearch, PetscViewer *monitor)
 #undef __FUNCT__
 #define __FUNCT__ "SNESLineSearchView"
 /*@
-   SNESLineSearchView - Prints useful information about the line search not
-   related to an individual call.
+   SNESLineSearchView - Prints useful information about the line search
 
    Input Parameters:
 .  linesearch - linesearch context
 
    Level: intermediate
 
-.seealso: SNESLineSearchCreate()
+.seealso: SNESLineSearchCreate(), SNESLineSearchMonitor()
 @*/
 PetscErrorCode SNESLineSearchView(SNESLineSearch linesearch, PetscViewer viewer)
 {
 /*@C
    SNESLineSearchSetType - Sets the linesearch type
 
+   Logically Collective on SNESLineSearch
+
    Input Parameters:
 +  linesearch - linesearch context
 -  type - The type of line search to be used
 .  cp - Critical point secant line search assuming F(x) = grad G(x) for some unknown G(x)
 -  shell - User provided SNESLineSearch implementation
 
-   Logically Collective on SNESLineSearch
-
    Level: intermediate
 
-
 .seealso: SNESLineSearchCreate()
 @*/
 PetscErrorCode SNESLineSearchSetType(SNESLineSearch linesearch, SNESLineSearchType type)
    Level: developer
 
    Notes:
-   This happens automatically when the line search is gotten/created with
+   This happens automatically when the line search is obtained/created with
    SNESGetLineSearch().  This routine is therefore mainly called within SNES
    implementations.
 
    solution and the function.  For instance, SNESQN may be scaled by the
    line search lambda using the argument -snes_qn_scaling ls.
 
-
 .seealso: SNESLineSearchSetLambda(), SNESLineSearchGetDamping(), SNESLineSearchApply()
 @*/
 PetscErrorCode  SNESLineSearchGetLambda(SNESLineSearch linesearch,PetscReal *lambda)
 -  lambda - The last steplength.
 
    Notes:
-   This routine is typically used within implementations of SNESLineSearchApply
+   This routine is typically used within implementations of SNESLineSearchApply()
    to set the final steplength.  This routine (and SNESLineSearchGetLambda()) were
    added in order to facilitate Quasi-Newton methods that use the previous steplength
    as an inner scaling parameter.