Date: 2026-03-01T05:24:33+00:00

Actual source code: petsctaolinesearch.h

      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;
     49: PETSC_EXTERN const char *const *TaoLineSearchConvergedReasons;

     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[]);
     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);