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