Skip to main content
`Ctrl`+`K`

# SNESLineSearchApply

Computes the line-search update.

## Synopsis

    #include "petscsnes.h"
    PetscErrorCode SNESLineSearchApply(SNESLineSearch linesearch, Vec X, Vec F, PetscReal *fnorm, Vec Y)

Collective

## Input Parameter

- linesearch - The line search context

## Input/Output Parameters

- X - The current solution, on output the new solution

- F - The current function value, on output the new function value at the solution value `X`

- fnorm - The current norm of `F`, on output the new norm of `F`

- Y - The current search direction, on output the direction determined by the linesearch, i.e. `Xnew = Xold - lambda*Y`

## Options Database Keys

- -snes_linesearch_type type - See `SNESLineSearchType`

- -snes_linesearch_monitor [:filename] - Print progress of line searches

- -snes_linesearch_damping - The linesearch damping parameter, default is 1.0 (no damping)

- -snes_linesearch_norms - Turn on/off the linesearch norms computation (SNESLineSearchSetComputeNorms())

- -snes_linesearch_keeplambda - Keep the previous `lambda` as the initial guess

- -snes_linesearch_max_it - The number of iterations for iterative line searches

## Notes

This is typically called from within a `SNESSolve()` implementation in order to help with convergence of the nonlinear method. Various `SNES` types use line searches in different ways, but the overarching theme is that a line search is used to determine an optimal damping parameter (that is `lambda`) of a step at each iteration of the method. Each application of the line search may invoke `SNESComputeFunction()` several times, and therefore may be fairly expensive.

In certain situations `SNESLineSearchApply()` may directly set a `SNESConvergedReason` in the `SNES` object so one should always check this value immediately after the call to `SNESLineSearchApply()`.

## See Also

SNES: Nonlinear Solvers, `SNES`, `SNESLineSearch`, `SNESGetLineSearch()`, `SNESLineSearchCreate()`, `SNESLineSearchGetLambda()`, `SNESLineSearchPreCheck()`, `SNESLineSearchPostCheck()`, `SNESSolve()`, `SNESComputeFunction()`, `SNESLineSearchSetComputeNorms()`, `SNESLineSearchType`, `SNESLineSearchSetType()`

## Level

advanced

## Location

src/snes/linesearch/interface/linesearch.c

## Implementations

SNESLineSearchApply_NCGLinear() in src/snes/impls/ncg/snesncg.c
SNESLineSearchApply_Basic() in src/snes/linesearch/impls/basic/linesearchbasic.c
SNESLineSearchApply_Bisection() in src/snes/linesearch/impls/bisection/linesearchbisection.c
SNESLineSearchApply_BT() in src/snes/linesearch/impls/bt/linesearchbt.c
SNESLineSearchApply_CP() in src/snes/linesearch/impls/cp/linesearchcp.c
SNESLineSearchApply_NLEQERR() in src/snes/linesearch/impls/nleqerr/linesearchnleqerr.c
SNESLineSearchApply_Secant() in src/snes/linesearch/impls/secant/linesearchsecant.c
SNESLineSearchApply_Shell() in src/snes/linesearch/impls/shell/linesearchshell.c

Index of all SNES routines
Table of Contents for all manual pages
Index of all manual pages