PETSc version 3.16.5
Fix/Edit manual page

# TaoLineSearchApply

Performs a line-search in a given step direction. Criteria for acceptable step length depends on the line-search algorithm chosen

### Synopsis

    #include "petsctaolinesearch.h"
    PetscErrorCode TaoLineSearchApply(TaoLineSearch ls, Vec x, PetscReal *f, Vec g, Vec s, PetscReal *steplength, TaoLineSearchConvergedReason *reason)

Collective on TaoLineSearch

### Input Parameters

| ls | - the Tao context
| s | - search direction

### Input/Output Parameters

| x | - The current solution (on output x contains the new solution determined by the line search)
| f | - objective function value at current solution (on output contains the objective function value at new solution)
| g | - gradient evaluated at x (on output contains the gradient at new solution)

### Output Parameters

| steplength | - scalar multiplier of s used ( x = x0 + steplength * x)
| reason | - reason why the line-search stopped

### Notes

### reason will be set to one of

| TAOLINESEARCH_FAILED_ASCENT | - initial line search step * g is not descent direction
| TAOLINESEARCH_FAILED_INFORNAN | - function evaluation gives Inf or Nan value
| TAOLINESEARCH_FAILED_BADPARAMETER | - negative value set as parameter
| TAOLINESEARCH_HALTED_MAXFCN | - maximum number of function evaluation reached
| TAOLINESEARCH_HALTED_UPPERBOUND | - step is at upper bound
| TAOLINESEARCH_HALTED_LOWERBOUND | - step is at lower bound
| TAOLINESEARCH_HALTED_RTOL | - range of uncertainty is smaller than given tolerance
| TAOLINESEARCH_HALTED_USER | - user can set this reason to stop line search
| TAOLINESEARCH_HALTED_OTHER | - any other reason
| TAOLINESEARCH_SUCCESS | - successful line search

The algorithm developer must set up the TaoLineSearch with calls to TaoLineSearchSetObjectiveRoutine() and TaoLineSearchSetGradientRoutine(), TaoLineSearchSetObjectiveAndGradientRoutine(), or TaoLineSearchUseTaoRoutines()

You may or may not need to follow this with a call to TaoAddLineSearchCounts(), depending on whether you want these evaluations to count toward the total function/gradient evaluations.

.seealso: TaoLineSearchCreate(), TaoLineSearchSetType(), TaoLineSearchSetInitialStepLength(), TaoAddLineSearchCounts()

### Level

beginner

### Location

src/tao/linesearch/interface/taolinesearch.c

### Implementations

TaoLineSearchApply_Armijo in src/tao/linesearch/impls/armijo/armijo.c
TaoLineSearchApply_GPCG in src/tao/linesearch/impls/gpcglinesearch/gpcglinesearch.c
TaoLineSearchApply_MT in src/tao/linesearch/impls/morethuente/morethuente.c
TaoLineSearchApply_OWArmijo in src/tao/linesearch/impls/owarmijo/owarmijo.c
TaoLineSearchApply_Unit in src/tao/linesearch/impls/unit/unit.c
Index of all TaoLineSearch routines
Table of Contents for all manual pages
Index of all manual pages