1 #ifndef PETSCTAOLINESEARCH_H 2 #define PETSCTAOLINESEARCH_H 3 4 /* SUBMANSEC = Tao */ 5 6 /*S 7 TaoLineSearch - PETSc object that manages line searches for the `Tao` optimization solves 8 9 Level: intermediate 10 11 .seealso: [](chapter_tao), `TaoLineSearchType`, `Tao`, `TaoCreate()`, `TaoDestroy()`, `TaoSetType()`, `TaoType` 12 S*/ 13 typedef struct _p_TaoLineSearch *TaoLineSearch; 14 15 #include <petsctao.h> 16 17 /*E 18 TaoLineSearchConvergedReason - reason a `TaoLineSearch` completed 19 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 31 32 Level: beginner 33 34 .seealso: [](chapter_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; 50 51 /*J 52 TaoLineSearchType - String with the name of a `TaoLineSearch` method 53 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" 61 62 Options Database Key: 63 . -tao_ls_type <type> - select which method Tao should use at runtime 64 Values: 65 66 Level: beginner 67 68 .seealso: [](chapter_tao), `Tao`, `TaoLineSearch`, `TaoLineSearchSetType()`, `TaoCreate()`, `TaoSetType()` 69 J*/ 70 typedef const char *TaoLineSearchType; 71 #define TAOLINESEARCHUNIT "unit" 72 #define TAOLINESEARCHMT "more-thuente" 73 #define TAOLINESEARCHGPCG "gpcg" 74 #define TAOLINESEARCHARMIJO "armijo" 75 #define TAOLINESEARCHOWARMIJO "owarmijo" 76 #define TAOLINESEARCHIPM "ipm" 77 78 PETSC_EXTERN PetscClassId TAOLINESEARCH_CLASSID; 79 PETSC_EXTERN PetscFunctionList TaoLineSearchList; 80 81 PETSC_EXTERN PetscErrorCode TaoLineSearchCreate(MPI_Comm, TaoLineSearch *); 82 PETSC_EXTERN PetscErrorCode TaoLineSearchSetFromOptions(TaoLineSearch); 83 PETSC_EXTERN PetscErrorCode TaoLineSearchSetUp(TaoLineSearch); 84 PETSC_EXTERN PetscErrorCode TaoLineSearchDestroy(TaoLineSearch *); 85 PETSC_EXTERN PetscErrorCode TaoLineSearchMonitor(TaoLineSearch, PetscInt, PetscReal, PetscReal); 86 PETSC_EXTERN PetscErrorCode TaoLineSearchView(TaoLineSearch, PetscViewer); 87 PETSC_EXTERN PetscErrorCode TaoLineSearchViewFromOptions(TaoLineSearch, PetscObject, const char[]); 88 89 PETSC_EXTERN PetscErrorCode TaoLineSearchSetOptionsPrefix(TaoLineSearch, const char prefix[]); 90 PETSC_EXTERN PetscErrorCode TaoLineSearchReset(TaoLineSearch); 91 PETSC_EXTERN PetscErrorCode TaoLineSearchAppendOptionsPrefix(TaoLineSearch, const char[]); 92 PETSC_EXTERN PetscErrorCode TaoLineSearchGetOptionsPrefix(TaoLineSearch, const char *[]); 93 PETSC_EXTERN PetscErrorCode TaoLineSearchApply(TaoLineSearch, Vec, PetscReal *, Vec, Vec, PetscReal *, TaoLineSearchConvergedReason *); 94 PETSC_EXTERN PetscErrorCode TaoLineSearchGetStepLength(TaoLineSearch, PetscReal *); 95 PETSC_EXTERN PetscErrorCode TaoLineSearchGetStartingVector(TaoLineSearch, Vec *); 96 PETSC_EXTERN PetscErrorCode TaoLineSearchGetStepDirection(TaoLineSearch, Vec *); 97 PETSC_EXTERN PetscErrorCode TaoLineSearchSetInitialStepLength(TaoLineSearch, PetscReal); 98 PETSC_EXTERN PetscErrorCode TaoLineSearchGetSolution(TaoLineSearch, Vec, PetscReal *, Vec, PetscReal *, TaoLineSearchConvergedReason *); 99 PETSC_EXTERN PetscErrorCode TaoLineSearchGetFullStepObjective(TaoLineSearch, PetscReal *); 100 PETSC_EXTERN PetscErrorCode TaoLineSearchGetNumberFunctionEvaluations(TaoLineSearch, PetscInt *, PetscInt *, PetscInt *); 101 102 PETSC_EXTERN PetscErrorCode TaoLineSearchGetType(TaoLineSearch, TaoLineSearchType *); 103 PETSC_EXTERN PetscErrorCode TaoLineSearchSetType(TaoLineSearch, TaoLineSearchType); 104 105 PETSC_EXTERN PetscErrorCode TaoLineSearchIsUsingTaoRoutines(TaoLineSearch, PetscBool *); 106 PETSC_EXTERN PetscErrorCode TaoLineSearchSetObjectiveAndGTSRoutine(TaoLineSearch, PetscErrorCode (*)(TaoLineSearch, Vec, Vec, PetscReal *, PetscReal *, void *), void *); 107 PETSC_EXTERN PetscErrorCode TaoLineSearchSetObjectiveRoutine(TaoLineSearch, PetscErrorCode (*)(TaoLineSearch, Vec, PetscReal *, void *), void *); 108 PETSC_EXTERN PetscErrorCode TaoLineSearchSetGradientRoutine(TaoLineSearch, PetscErrorCode (*)(TaoLineSearch, Vec, Vec, void *), void *); 109 PETSC_EXTERN PetscErrorCode TaoLineSearchSetObjectiveAndGradientRoutine(TaoLineSearch, PetscErrorCode (*)(TaoLineSearch, Vec, PetscReal *, Vec, void *), void *); 110 111 PETSC_EXTERN PetscErrorCode TaoLineSearchComputeObjective(TaoLineSearch, Vec, PetscReal *); 112 PETSC_EXTERN PetscErrorCode TaoLineSearchComputeGradient(TaoLineSearch, Vec, Vec); 113 PETSC_EXTERN PetscErrorCode TaoLineSearchComputeObjectiveAndGradient(TaoLineSearch, Vec, PetscReal *, Vec); 114 PETSC_EXTERN PetscErrorCode TaoLineSearchComputeObjectiveAndGTS(TaoLineSearch, Vec, PetscReal *, PetscReal *); 115 PETSC_EXTERN PetscErrorCode TaoLineSearchSetVariableBounds(TaoLineSearch, Vec, Vec); 116 117 PETSC_EXTERN PetscErrorCode TaoLineSearchInitializePackage(void); 118 PETSC_EXTERN PetscErrorCode TaoLineSearchFinalizePackage(void); 119 120 PETSC_EXTERN PetscErrorCode TaoLineSearchRegister(const char[], PetscErrorCode (*)(TaoLineSearch)); 121 PETSC_EXTERN PetscErrorCode TaoLineSearchUseTaoRoutines(TaoLineSearch, Tao); 122 123 #endif 124