Actual source code: petsctaolinesearch.h

  1: #ifndef PETSCTAOLINESEARCH_H
  2: #define PETSCTAOLINESEARCH_H

  4: /* SUBMANSEC = Tao */

  6: /*S
  7:    TaoLineSearch - PETSc object that manages line searches for the `Tao` optimization solves

  9:    Level: intermediate

 11: .seealso: [](ch_tao), `TaoLineSearchType`, `Tao`, `TaoCreate()`, `TaoDestroy()`, `TaoSetType()`, `TaoType`
 12: S*/
 13: typedef struct _p_TaoLineSearch *TaoLineSearch;

 15: #include <petsctao.h>

 17: /*E
 18:     TaoLineSearchConvergedReason - reason a `TaoLineSearch` completed

 20:    Values:
 21: + `TAOLINESEARCH_FAILED_ASCENT` - initial line search step * g is not descent direction
 22: . `TAOLINESEARCH_FAILED_INFORNAN` - function evaluation gives `Inf` or `Nan` value
 23: . `TAOLINESEARCH_FAILED_BADPARAMETER` - negative value set as parameter
 24: . `TAOLINESEARCH_HALTED_MAXFCN` - maximum number of function evaluation reached
 25: . `TAOLINESEARCH_HALTED_UPPERBOUND` - step is at upper bound
 26: . `TAOLINESEARCH_HALTED_LOWERBOUND` - step is at lower bound
 27: . `TAOLINESEARCH_HALTED_RTOL` - range of uncertainty is smaller than given tolerance
 28: . `TAOLINESEARCH_HALTED_USER` - user can set this reason to stop line search
 29: . `TAOLINESEARCH_HALTED_OTHER` - any other reason
 30: - `TAOLINESEARCH_SUCCESS` - successful line search

 32:    Level: beginner

 34: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoSolve()`, `TaoGetConvergedReason()`, `KSPConvergedReason`, `SNESConvergedReason`
 35: E*/
 36: typedef enum {
 37:   TAOLINESEARCH_FAILED_INFORNAN     = -1,
 38:   TAOLINESEARCH_FAILED_BADPARAMETER = -2,
 39:   TAOLINESEARCH_FAILED_ASCENT       = -3,
 40:   TAOLINESEARCH_CONTINUE_ITERATING  = 0,
 41:   TAOLINESEARCH_SUCCESS             = 1,
 42:   TAOLINESEARCH_SUCCESS_USER        = 2,
 43:   TAOLINESEARCH_HALTED_OTHER        = 3,
 44:   TAOLINESEARCH_HALTED_MAXFCN       = 4,
 45:   TAOLINESEARCH_HALTED_UPPERBOUND   = 5,
 46:   TAOLINESEARCH_HALTED_LOWERBOUND   = 6,
 47:   TAOLINESEARCH_HALTED_RTOL         = 7,
 48:   TAOLINESEARCH_HALTED_USER         = 8
 49: } TaoLineSearchConvergedReason;

 51: /*J
 52:         TaoLineSearchType - String with the name of a `TaoLineSearch` method

 54:    Values:
 55: +   `TAOLINESEARCHUNIT` -  "unit" do not perform a line search and always accept unit step length
 56: .   `TAOLINESEARCHMT` - "more-thuente" line search with a cubic model enforcing the strong Wolfe/curvature condition
 57: .   `TAOLINESEARCHGPCG` - "gpcg"
 58: .   `TAOLINESEARCHARMIJO` - "armijo" simple backtracking line search enforcing only the sufficient decrease condition
 59: .   `TAOLINESEARCHOWARMIJO` - "owarmijo"
 60: -   `TAOLINESEARCHIPM` - "ipm"

 62:   Options Database Key:
 63: .  -tao_ls_type <type> - select which method Tao should use at runtime

 65:   Level: beginner

 67: .seealso: [](ch_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchSetType()`, `TaoCreate()`, `TaoSetType()`
 68: J*/
 69: typedef const char *TaoLineSearchType;
 70: #define TAOLINESEARCHUNIT     "unit"
 71: #define TAOLINESEARCHMT       "more-thuente"
 72: #define TAOLINESEARCHGPCG     "gpcg"
 73: #define TAOLINESEARCHARMIJO   "armijo"
 74: #define TAOLINESEARCHOWARMIJO "owarmijo"
 75: #define TAOLINESEARCHIPM      "ipm"

 77: PETSC_EXTERN PetscClassId      TAOLINESEARCH_CLASSID;
 78: PETSC_EXTERN PetscFunctionList TaoLineSearchList;

 80: PETSC_EXTERN PetscErrorCode TaoLineSearchCreate(MPI_Comm, TaoLineSearch *);
 81: PETSC_EXTERN PetscErrorCode TaoLineSearchSetFromOptions(TaoLineSearch);
 82: PETSC_EXTERN PetscErrorCode TaoLineSearchSetUp(TaoLineSearch);
 83: PETSC_EXTERN PetscErrorCode TaoLineSearchDestroy(TaoLineSearch *);
 84: PETSC_EXTERN PetscErrorCode TaoLineSearchMonitor(TaoLineSearch, PetscInt, PetscReal, PetscReal);
 85: PETSC_EXTERN PetscErrorCode TaoLineSearchView(TaoLineSearch, PetscViewer);
 86: PETSC_EXTERN PetscErrorCode TaoLineSearchViewFromOptions(TaoLineSearch, PetscObject, const char[]);

 88: PETSC_EXTERN PetscErrorCode TaoLineSearchSetOptionsPrefix(TaoLineSearch, const char prefix[]);
 89: PETSC_EXTERN PetscErrorCode TaoLineSearchReset(TaoLineSearch);
 90: PETSC_EXTERN PetscErrorCode TaoLineSearchAppendOptionsPrefix(TaoLineSearch, const char[]);
 91: PETSC_EXTERN PetscErrorCode TaoLineSearchGetOptionsPrefix(TaoLineSearch, const char *[]);
 92: PETSC_EXTERN PetscErrorCode TaoLineSearchApply(TaoLineSearch, Vec, PetscReal *, Vec, Vec, PetscReal *, TaoLineSearchConvergedReason *);
 93: PETSC_EXTERN PetscErrorCode TaoLineSearchGetStepLength(TaoLineSearch, PetscReal *);
 94: PETSC_EXTERN PetscErrorCode TaoLineSearchGetStartingVector(TaoLineSearch, Vec *);
 95: PETSC_EXTERN PetscErrorCode TaoLineSearchGetStepDirection(TaoLineSearch, Vec *);
 96: PETSC_EXTERN PetscErrorCode TaoLineSearchSetInitialStepLength(TaoLineSearch, PetscReal);
 97: PETSC_EXTERN PetscErrorCode TaoLineSearchGetSolution(TaoLineSearch, Vec, PetscReal *, Vec, PetscReal *, TaoLineSearchConvergedReason *);
 98: PETSC_EXTERN PetscErrorCode TaoLineSearchGetFullStepObjective(TaoLineSearch, PetscReal *);
 99: PETSC_EXTERN PetscErrorCode TaoLineSearchGetNumberFunctionEvaluations(TaoLineSearch, PetscInt *, PetscInt *, PetscInt *);

101: PETSC_EXTERN PetscErrorCode TaoLineSearchGetType(TaoLineSearch, TaoLineSearchType *);
102: PETSC_EXTERN PetscErrorCode TaoLineSearchSetType(TaoLineSearch, TaoLineSearchType);

104: PETSC_EXTERN PetscErrorCode TaoLineSearchIsUsingTaoRoutines(TaoLineSearch, PetscBool *);
105: PETSC_EXTERN PetscErrorCode TaoLineSearchSetObjectiveAndGTSRoutine(TaoLineSearch, PetscErrorCode (*)(TaoLineSearch, Vec, Vec, PetscReal *, PetscReal *, void *), void *);
106: PETSC_EXTERN PetscErrorCode TaoLineSearchSetObjectiveRoutine(TaoLineSearch, PetscErrorCode (*)(TaoLineSearch, Vec, PetscReal *, void *), void *);
107: PETSC_EXTERN PetscErrorCode TaoLineSearchSetGradientRoutine(TaoLineSearch, PetscErrorCode (*)(TaoLineSearch, Vec, Vec, void *), void *);
108: PETSC_EXTERN PetscErrorCode TaoLineSearchSetObjectiveAndGradientRoutine(TaoLineSearch, PetscErrorCode (*)(TaoLineSearch, Vec, PetscReal *, Vec, void *), void *);

110: PETSC_EXTERN PetscErrorCode TaoLineSearchComputeObjective(TaoLineSearch, Vec, PetscReal *);
111: PETSC_EXTERN PetscErrorCode TaoLineSearchComputeGradient(TaoLineSearch, Vec, Vec);
112: PETSC_EXTERN PetscErrorCode TaoLineSearchComputeObjectiveAndGradient(TaoLineSearch, Vec, PetscReal *, Vec);
113: PETSC_EXTERN PetscErrorCode TaoLineSearchComputeObjectiveAndGTS(TaoLineSearch, Vec, PetscReal *, PetscReal *);
114: PETSC_EXTERN PetscErrorCode TaoLineSearchSetVariableBounds(TaoLineSearch, Vec, Vec);

116: PETSC_EXTERN PetscErrorCode TaoLineSearchInitializePackage(void);
117: PETSC_EXTERN PetscErrorCode TaoLineSearchFinalizePackage(void);

119: PETSC_EXTERN PetscErrorCode TaoLineSearchRegister(const char[], PetscErrorCode (*)(TaoLineSearch));
120: PETSC_EXTERN PetscErrorCode TaoLineSearchUseTaoRoutines(TaoLineSearch, Tao);

122: #endif