1: #pragma once

  3: /* SUBMANSEC = Tao */

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

  8:    Level: intermediate

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

 14: #include <petsctao.h>

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

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

 31:    Level: beginner

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

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

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

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

 64:    Level: beginner

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

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

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

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

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

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

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

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

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