petsc-3.7.7 2017-09-25
Report Typos and Errors

# 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
| 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)
| s | - search direction

### Output Parameters

| x | - new solution
| f | - objective function value at x
| g | - gradient vector at x
| steplength | - scalar multiplier of s used ( x = x0 + steplength * x )
| reason | - reason why the line-search stopped

### 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

### Note

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

### Note

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
Index of all TaoLineSearch routines
Table of Contents for all manual pages
Index of all manual pages