scipy.optimize._dcsrch:DCSRCH

Notes

This subroutine finds a step that satisfies a sufficient decrease condition and a curvature condition.

Each call of the subroutine updates an interval with endpoints stx and sty. The interval is initially chosen so that it contains a minimizer of the modified function

psi(stp) = f(stp) - f(0) - ftol*stp*f'(0).

If psi(stp) <= 0 and f'(stp) >= 0 for some step, then the interval is chosen so that it contains a minimizer of f.

The algorithm is designed to find a step that satisfies the sufficient decrease condition

f(stp) <= f(0) + ftol*stp*f'(0),

and the curvature condition

abs(f'(stp)) <= gtol*abs(f'(0)).

If ftol is less than gtol and if, for example, the function is bounded below, then there is always a step which satisfies both conditions.

If no step can be found that satisfies both conditions, then the algorithm stops with a warning. In this case stp only satisfies the sufficient decrease condition.

A typical invocation of dcsrch has the following outline:

Evaluate the function at stp = 0.0d0; store in f. Evaluate the gradient at stp = 0.0d0; store in g. Choose a starting step stp.

task = 'START' 10 continue call dcsrch(stp,f,g,ftol,gtol,xtol,task,stpmin,stpmax, isave,dsave) if (task .eq. 'FG') then Evaluate the function and the gradient at stp go to 10 end if

NOTE: The user must not alter work arrays between calls.

The subroutine statement is

subroutine dcsrch(f,g,stp,ftol,gtol,xtol,stpmin,stpmax,

task,isave,dsave)

where stp is a double precision variable. On entry stp is the current estimate of a satisfactory

step. On initial entry, a positive initial estimate must be provided.

On exit stp is the current estimate of a satisfactory step

if task = 'FG'. If task = 'CONV' then stp satisfies the sufficient decrease and curvature condition.

f is a double precision variable.

On initial entry f is the value of the function at 0. On subsequent entries f is the value of the function at stp. On exit f is the value of the function at stp.

g is a double precision variable.

On initial entry g is the derivative of the function at 0. On subsequent entries g is the derivative of the function at stp. On exit g is the derivative of the function at stp.

ftol is a double precision variable.

On entry ftol specifies a nonnegative tolerance for the

sufficient decrease condition.

On exit ftol is unchanged. gtol is a double precision variable. On entry gtol specifies a nonnegative tolerance for the

curvature condition.

On exit gtol is unchanged. xtol is a double precision variable. On entry xtol specifies a nonnegative relative tolerance

for an acceptable step. The subroutine exits with a warning if the relative difference between sty and stx is less than xtol.

On exit xtol is unchanged.

task is a character variable of length at least 60.

On initial entry task must be set to 'START'. On exit task indicates the required action:

If task(1:2) = 'FG' then evaluate the function and derivative at stp and call dcsrch again.

If task(1:4) = 'CONV' then the search is successful.

If task(1:4) = 'WARN' then the subroutine is not able to satisfy the convergence conditions. The exit value of stp contains the best point found during the search.

If task(1:5) = 'ERROR' then there is an error in the input arguments.

On exit with convergence, a warning or an error, the

variable task contains additional information.

stpmin is a double precision variable.

On entry stpmin is a nonnegative lower bound for the step. On exit stpmin is unchanged.

stpmax is a double precision variable.

On entry stpmax is a nonnegative upper bound for the step. On exit stpmax is unchanged.

isave is an integer work array of dimension 2.

dsave is a double precision work array of dimension 13.

Subprograms called

MINPACK-2 ... dcstep

MINPACK-1 Project. June 1983. Argonne National Laboratory. Jorge J. More' and David J. Thuente.

MINPACK-2 Project. November 1993. Argonne National Laboratory and University of Minnesota. Brett M. Averick, Richard G. Carter, and Jorge J. More'.