@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 1996-2025 The Octave Project Developers
@c
@c This file is part of Octave.
@c
@c Octave is free software: you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <https://www.gnu.org/licenses/>.

@node Nonlinear Equations
@chapter Nonlinear Equations
@cindex nonlinear equations
@cindex equations, nonlinear

@menu
* Solvers::
* Minimizers::
@end menu

@node Solvers
@section Solvers

Octave can solve sets of nonlinear equations of the form
@tex
$$
 f (x) = 0
$$
@end tex
@ifnottex

@example
F (x) = 0
@end example

@end ifnottex

@noindent
using the function @code{fsolve}, which is based on the @sc{minpack}
subroutine @code{hybrd}.  This is an iterative technique so a starting
point must be provided.  This also has the consequence that
convergence is not guaranteed even if a solution exists.

@c fsolve scripts/optimization/fsolve.m
@anchor{XREFfsolve}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{x} =} fsolve (@var{fcn}, @var{x0})
@deftypefnx {} {@var{x} =} fsolve (@var{fcn}, @var{x0}, @var{options})
@deftypefnx {} {[@var{x}, @var{fval}] =} fsolve (@dots{})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}] =} fsolve (@dots{})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fsolve (@dots{})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}, @var{fjac}] =} fsolve (@dots{})
Solve a system of nonlinear equations defined by the function @var{fcn}.

@var{fcn} is a function handle, inline function, or string containing the
name of the function to evaluate.  @var{fcn} should accept a vector (array)
defining the unknown variables, and return a vector of left-hand sides of
the equations.  Right-hand sides are defined to be zeros.  In other words,
this function attempts to determine a vector @var{x} such that
@code{@var{fcn} (@var{x})} gives (approximately) all zeros.

@var{x0} is an initial guess for the solution.  The shape of @var{x0} is
preserved in all calls to @var{fcn}, but otherwise is treated as a column
vector.

@var{options} is a structure specifying additional parameters which
control the algorithm.  Currently, @code{fsolve} recognizes these options:
@qcode{"AutoScaling"}, @qcode{"ComplexEqn"}, @qcode{"FinDiffType"},
@qcode{"FunValCheck"}, @qcode{"Jacobian"}, @qcode{"MaxFunEvals"},
@qcode{"MaxIter"}, @qcode{"OutputFcn"}, @qcode{"TolFun"}, @qcode{"TolX"},
@qcode{"TypicalX"}, and @qcode{"Updating"}.

If @qcode{"AutoScaling"} is @qcode{"on"}, the variables will be
automatically scaled according to the column norms of the (estimated)
Jacobian.  As a result, @qcode{"TolFun"} becomes scaling-independent.  By
default, this option is @qcode{"off"} because it may sometimes deliver
unexpected (though mathematically correct) results.

If @qcode{"ComplexEqn"} is @qcode{"on"}, @code{fsolve} will attempt to solve
complex equations in complex variables, assuming that the equations possess
a complex derivative (i.e., are holomorphic).  If this is not what you want,
you should unpack the real and imaginary parts of the system to get a real
system.

If @qcode{"Jacobian"} is @qcode{"on"}, it specifies that @var{fcn}---when
called with 2 output arguments---also returns the Jacobian matrix of
right-hand sides at the requested point.

@qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
before optimization is halted.  The default value is
@code{100 * number_of_variables}, i.e., @code{100 * length (@var{x0})}.
The value must be a positive integer.

If @qcode{"Updating"} is @qcode{"on"}, the function will attempt to use
@nospell{Broyden} updates to update the Jacobian, in order to reduce the
number of Jacobian calculations.  If your user function always calculates
the Jacobian (regardless of number of output arguments) then this option
provides no advantage and should be disabled.

@qcode{"TolX"} specifies the termination tolerance in the unknown variables,
while @qcode{"TolFun"} is a tolerance for equations.  Default is @code{1e-6}
for both @qcode{"TolX"} and @qcode{"TolFun"}.

For a description of the other options,
@pxref{XREFoptimset,,@code{optimset}}.  To initialize an options structure
with default values for @code{fsolve} use
@code{options = optimset ("fsolve")}.

The first output @var{x} is the solution while the second output @var{fval}
contains the value of the function @var{fcn} evaluated at @var{x} (ideally
a vector of all zeros).

The third output @var{info} reports whether the algorithm succeeded and may
take one of the following values:

@table @asis
@item 1
Converged to a solution point.  Relative residual error is less than
specified by @code{TolFun}.

@item 2
Last relative step size was less than @code{TolX}.

@item 3
Last relative decrease in residual was less than @code{TolFun}.

@item 0
Iteration limit (either @code{MaxIter} or @code{MaxFunEvals}) exceeded.

@item -1
Stopped by @code{OutputFcn}.

@item -2
The Jacobian became excessively small and the search stalled.

@item -3
The trust region radius became excessively small.
@end table

@var{output} is a structure containing runtime information about the
@code{fsolve} algorithm.  Fields in the structure are:

@table @code
@item iterations
 Number of iterations through loop.

@item successful
 Number of successful iterations.

@item @nospell{funcCount}
 Number of function evaluations.

@end table

The final output @var{fjac} contains the value of the Jacobian evaluated
at @var{x}.

Note: If you only have a single nonlinear equation of one variable, using
@code{fzero} is usually a much better idea.

Note about user-supplied Jacobians:
As an inherent property of the algorithm, a Jacobian is always requested for
a solution vector whose residual vector is already known, and it is the last
accepted successful step.  Often this will be one of the last two calls, but
not always.  If the savings by reusing intermediate results from residual
calculation in Jacobian calculation are significant, the best strategy is to
employ @code{OutputFcn}: After a vector is evaluated for residuals, if
@code{OutputFcn} is called with that vector, then the intermediate results
should be saved for future Jacobian evaluation, and should be kept until a
Jacobian evaluation is requested or until @code{OutputFcn} is called with a
different vector, in which case they should be dropped in favor of this most
recent vector.  A short example how this can be achieved follows:

@example
function [fval, fjac] = user_fcn (x, optimvalues, state)
persistent sav = [], sav0 = [];
if (nargin == 1)
  ## evaluation call
  if (nargout == 1)
    sav0.x = x;  # mark saved vector
    ## calculate fval, save results to sav0.
  elseif (nargout == 2)
    ## calculate fjac using sav.
  endif
else
  ## outputfcn call.
  if (all (x == sav0.x))
    sav = sav0;
  endif
  ## maybe output iteration status, etc.
endif
endfunction

## @dots{}

fsolve (@@user_fcn, x0, optimset ("OutputFcn", @@user_fcn, @dots{}))
@end example
@xseealso{@ref{XREFfzero,,fzero}, @ref{XREFoptimset,,optimset}}
@end deftypefn


The following is a complete example.  To solve the set of equations
@tex
$$
 \eqalign{-2x^2 + 3xy + 4\sin(y) - 6 &= 0\cr
           3x^2 - 2xy^2 + 3\cos(x) + 4 &= 0}
$$
@end tex
@ifnottex

@example
@group
-2x^2 + 3xy   + 4 sin(y) = 6
 3x^2 - 2xy^2 + 3 cos(x) = -4
@end group
@end example

@end ifnottex

@noindent
you first need to write a function to compute the value of the given
function.  For example:

@example
@group
function y = f (x)
  y = zeros (2, 1);
  y(1) = -2*x(1)^2 + 3*x(1)*x(2)   + 4*sin(x(2)) - 6;
  y(2) =  3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4;
endfunction
@end group
@end example

Then, call @code{fsolve} with a specified initial condition to find the
roots of the system of equations.  For example, given the function
@code{f} defined above,

@example
[x, fval, info] = fsolve (@@f, [1; 2])
@end example

@noindent
results in the solution

@example
@group
x =

  0.57983
  2.54621

fval =

  -5.7184e-10
   5.5460e-10

info = 1
@end group
@end example

@noindent
A value of @code{info = 1} indicates that the solution has converged.

When no Jacobian is supplied (as in the example above) it is approximated
numerically.  This requires more function evaluations, and hence is
less efficient.  In the example above we could compute the Jacobian
analytically as

@iftex
@tex
$$
\left[\matrix{ {\partial f_1 \over \partial x_1} &
               {\partial f_1 \over \partial x_2} \cr
               {\partial f_2 \over \partial x_1} &
               {\partial f_2 \over \partial x_2} \cr}\right] =
\left[\matrix{ 3 x_2 - 4 x_1                  &
               4 \cos(x_2) + 3 x_1            \cr
               -2 x_2^2 - 3 \sin(x_1) + 6 x_1 &
               -4 x_1 x_2                     \cr }\right]
$$
@end tex
and compute it with the following Octave function
@end iftex

@example
@group
function [y, jac] = f (x)
  y = zeros (2, 1);
  y(1) = -2*x(1)^2 + 3*x(1)*x(2)   + 4*sin(x(2)) - 6;
  y(2) =  3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4;
  if (nargout == 2)
    jac = zeros (2, 2);
    jac(1,1) =  3*x(2) - 4*x(1);
    jac(1,2) =  4*cos(x(2)) + 3*x(1);
    jac(2,1) = -2*x(2)^2 - 3*sin(x(1)) + 6*x(1);
    jac(2,2) = -4*x(1)*x(2);
  endif
endfunction
@end group
@end example

@noindent
The Jacobian can then be used with the following call to @code{fsolve}:

@example
[x, fval, info] = fsolve (@@f, [1; 2], optimset ("jacobian", "on"));
@end example

@noindent
which gives the same solution as before.

@c fzero scripts/optimization/fzero.m
@anchor{XREFfzero}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{x} =} fzero (@var{fcn}, @var{x0})
@deftypefnx {} {@var{x} =} fzero (@var{fcn}, @var{x0}, @var{options})
@deftypefnx {} {[@var{x}, @var{fval}] =} fzero (@dots{})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}] =} fzero (@dots{})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fzero (@dots{})
Find a zero of a univariate function.

@var{fcn} is a function handle, inline function, or string containing the
name of the function to evaluate.

@var{x0} should be a two-element vector specifying two points which
bracket a zero.  In other words, there must be a change in sign of the
function between @var{x0}(1) and @var{x0}(2).  More mathematically, the
following must hold

@example
sign (@var{fcn}(@var{x0}(1))) * sign (@var{fcn}(@var{x0}(2))) <= 0
@end example

If @var{x0} is a single scalar then several nearby and distant values are
probed in an attempt to obtain a valid bracketing.  If this is not
successful, the function fails.

@var{options} is a structure specifying additional options.  Currently,
@code{fzero} recognizes these options:
@qcode{"Display"}, @qcode{"FunValCheck"}, @qcode{"MaxFunEvals"},
@qcode{"MaxIter"}, @qcode{"OutputFcn"}, and @qcode{"TolX"}.

@qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
before the search is halted.  The default value is @code{Inf}.
The value must be a positive integer.

@qcode{"MaxIter"} proscribes the maximum number of algorithm iterations
before the search is halted.  The default value is @code{Inf}.
The value must be a positive integer.

@qcode{"TolX"} specifies the termination tolerance for the solution @var{x}.
The default value is @code{eps}.

For a description of the other options,
@pxref{XREFoptimset,,@code{optimset}}.
To initialize an options structure with default values for @code{fzero} use
@code{options = optimset ("fzero")}.

On exit, the function returns @var{x}, the approximate zero point, and
@var{fval}, the function evaluated at @var{x}.

The third output @var{info} reports whether the algorithm succeeded and
may take one of the following values:

@itemize
@item 1
 The algorithm converged to a solution.

@item 0
 Maximum number of iterations or function evaluations has been reached.

@item -1
The algorithm has been terminated by a user @code{OutputFcn}.

@item -5
The algorithm may have converged to a singular point.
@end itemize

@var{output} is a structure containing runtime information about the
@code{fzero} algorithm.  Fields in the structure are:

@itemize
@item iterations
 Number of iterations through loop.

@item @nospell{funcCount}
 Number of function evaluations.

@item algorithm
 The string @qcode{"bisection, interpolation"}.

@item bracketx
 A two-element vector with the final bracketing of the zero along the
x-axis.

@item brackety
 A two-element vector with the final bracketing of the zero along the
y-axis.
@end itemize
@xseealso{@ref{XREFoptimset,,optimset}, @ref{XREFfsolve,,fsolve}}
@end deftypefn


@node Minimizers
@section Minimizers
@cindex local minimum
@cindex finding minimums

Often it is useful to find the minimum value of a function rather than just
the zeroes where it crosses the x-axis.  @code{fminbnd} is designed for the
simpler, but very common, case of a univariate function where the interval
to search is bounded.  For unbounded minimization of a function with
potentially many variables use @code{fminunc} or @code{fminsearch}.  The two
functions use different internal algorithms and some knowledge of the objective
function is required.  For functions which can be differentiated,
@code{fminunc} is appropriate.  For functions with discontinuities, or for
which a gradient search would fail, use @code{fminsearch}.
@xref{Optimization} for minimization with the presence of constraint
functions.  Note that searches can be made for maxima by simply inverting the
objective function
@tex
($F_{max} = -F_{min}$).
@end tex
@ifnottex
(@code{Fto_max = -Fto_min}).
@end ifnottex

@c fminbnd scripts/optimization/fminbnd.m
@anchor{XREFfminbnd}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{x} =} fminbnd (@var{fcn}, @var{a}, @var{b})
@deftypefnx {} {@var{x} =} fminbnd (@var{fcn}, @var{a}, @var{b}, @var{options})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fminbnd (@dots{})
Find a minimum point of a univariate function.

@var{fcn} is a function handle, inline function, or string containing the
name of the function to evaluate.

The starting interval is specified by @var{a} (left boundary) and @var{b}
(right boundary).  The endpoints must be finite.

@var{options} is a structure specifying additional parameters which
control the algorithm.  Currently, @code{fminbnd} recognizes these options:
@qcode{"Display"}, @qcode{"FunValCheck"}, @qcode{"MaxFunEvals"},
@qcode{"MaxIter"}, @qcode{"OutputFcn"}, @qcode{"TolX"}.

@qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
before optimization is halted.  The default value is 500.
The value must be a positive integer.

@qcode{"MaxIter"} proscribes the maximum number of algorithm iterations
before optimization is halted.  The default value is 500.
The value must be a positive integer.

@qcode{"TolX"} specifies the termination tolerance for the solution @var{x}.
The default is @code{1e-4}.

For a description of the other options,
@pxref{XREFoptimset,,@code{optimset}}.
To initialize an options structure with default values for @code{fminbnd}
use @code{options = optimset ("fminbnd")}.

On exit, the function returns @var{x}, the approximate minimum point, and
@var{fval}, the function evaluated @var{x}.

The third output @var{info} reports whether the algorithm succeeded and may
take one of the following values:

@itemize
@item 1
The algorithm converged to a solution.

@item 0
Iteration limit (either @code{MaxIter} or @code{MaxFunEvals}) exceeded.

@item -1
The algorithm was terminated by a user @code{OutputFcn}.
@end itemize

Application Notes:
@enumerate
@item
The search for a minimum is restricted to be in the
finite interval bound by @var{a} and @var{b}.  If you have only one initial
point to begin searching from then you will need to use an unconstrained
minimization algorithm such as @code{fminunc} or @code{fminsearch}.
@code{fminbnd} internally uses a Golden Section search strategy.

@item
Use @ref{Anonymous Functions} to pass additional parameters to @var{fcn}.
For specific examples of doing so for @code{fminbnd} and other
minimization functions see the @ref{Minimizers} section of the GNU Octave
manual.
@end enumerate
@xseealso{@ref{XREFfzero,,fzero}, @ref{XREFfminunc,,fminunc}, @ref{XREFfminsearch,,fminsearch}, @ref{XREFoptimset,,optimset}}
@end deftypefn


@c fminunc scripts/optimization/fminunc.m
@anchor{XREFfminunc}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{x} =} fminunc (@var{fcn}, @var{x0})
@deftypefnx {} {@var{x} =} fminunc (@var{fcn}, @var{x0}, @var{options})
@deftypefnx {} {[@var{x}, @var{fval}] =} fminunc (@var{fcn}, @dots{})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}] =} fminunc (@var{fcn}, @dots{})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fminunc (@var{fcn}, @dots{})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}, @var{grad}] =} fminunc (@var{fcn}, @dots{})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}, @var{grad}, @var{hess}] =} fminunc (@var{fcn}, @dots{})
Solve an unconstrained optimization problem defined by the function
@var{fcn}.

@code{fminunc} attempts to determine a vector @var{x} such that
@code{@var{fcn} (@var{x})} is a local minimum.

@var{fcn} is a function handle, inline function, or string containing the
name of the function to evaluate.  @var{fcn} should accept a vector (array)
defining the unknown variables, and return the objective function value,
optionally with gradient.

@var{x0} determines a starting guess.  The shape of @var{x0} is preserved in
all calls to @var{fcn}, but otherwise is treated as a column vector.

@var{options} is a structure specifying additional parameters which
control the algorithm.  Currently, @code{fminunc} recognizes these options:
@qcode{"AutoScaling"}, @qcode{"FinDiffType"}, @qcode{"FunValCheck"},
@qcode{"GradObj"}, @qcode{"MaxFunEvals"}, @qcode{"MaxIter"},
@qcode{"OutputFcn"}, @qcode{"TolFun"}, @qcode{"TolX"}, @qcode{"TypicalX"}.

If @qcode{"AutoScaling"} is @qcode{"on"}, the variables will be
automatically scaled according to the column norms of the (estimated)
Jacobian.  As a result, @qcode{"TolFun"} becomes scaling-independent.  By
default, this option is @qcode{"off"} because it may sometimes deliver
unexpected (though mathematically correct) results.

If @qcode{"GradObj"} is @qcode{"on"}, it specifies that @var{fcn}---when
called with two output arguments---also returns the Jacobian matrix of
partial first derivatives at the requested point.

@qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
before optimization is halted.  The default value is
@code{100 * number_of_variables}, i.e., @code{100 * length (@var{x0})}.
The value must be a positive integer.

@qcode{"MaxIter"} proscribes the maximum number of algorithm iterations
before optimization is halted.  The default value is 400.
The value must be a positive integer.

@qcode{"TolX"} specifies the termination tolerance for the unknown variables
@var{x}, while @qcode{"TolFun"} is a tolerance for the objective function
value @var{fval}.  The default is @code{1e-6} for both options.

For a description of the other options,
@pxref{XREFoptimset,,@code{optimset}}.

On return, @var{x} is the location of the minimum and @var{fval} contains
the value of the objective function at @var{x}.

@var{info} may be one of the following values:

@table @asis
@item 1
Converged to a solution point.  Relative gradient error is less than
specified by @code{TolFun}.

@item 2
Last relative step size was less than @code{TolX}.

@item 3
Last relative change in function value was less than @code{TolFun}.

@item 0
Iteration limit exceeded---either maximum number of algorithm iterations
@code{MaxIter} or maximum number of function evaluations @code{MaxFunEvals}.

@item -1
Algorithm terminated by @code{OutputFcn}.

@item -3
The trust region radius became excessively small.
@end table

Optionally, @code{fminunc} can return a structure with convergence
statistics (@var{output}), the output gradient (@var{grad}) at the
solution @var{x}, and approximate Hessian (@var{hess}) at the solution
@var{x}.

Application Notes:
@enumerate
@item
If the objective function is a single nonlinear equation
of one variable then using @code{fminbnd} is usually a better choice.

@item
The algorithm used by @code{fminunc} is a gradient search which depends
on the objective function being differentiable.  If the function has
discontinuities it may be better to use a derivative-free algorithm such as
@code{fminsearch}.

@item
Use @ref{Anonymous Functions} to pass additional parameters to @var{fcn}.
For specific examples of doing so for @code{fminunc} and other
minimization functions see the @ref{Minimizers} section of the GNU Octave
manual.
@end enumerate
@xseealso{@ref{XREFfminbnd,,fminbnd}, @ref{XREFfminsearch,,fminsearch}, @ref{XREFoptimset,,optimset}}
@end deftypefn


@c fminsearch scripts/optimization/fminsearch.m
@anchor{XREFfminsearch}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{x} =} fminsearch (@var{fcn}, @var{x0})
@deftypefnx {} {@var{x} =} fminsearch (@var{fcn}, @var{x0}, @var{options})
@deftypefnx {} {@var{x} =} fminsearch (@var{problem})
@deftypefnx {} {[@var{x}, @var{fval}, @var{exitflag}, @var{output}] =} fminsearch (@dots{})

Find a value of @var{x} which minimizes the multi-variable function
@var{fcn}.

@var{fcn} is a function handle, inline function, or string containing the
name of the function to evaluate.

The search begins at the point @var{x0} and iterates using the
@nospell{Nelder & Mead} Simplex algorithm (a derivative-free method).  This
algorithm is better-suited to functions which have discontinuities or for
which a gradient-based search such as @code{fminunc} fails.

Options for the search are provided in the parameter @var{options} using the
function @code{optimset}.  Currently, @code{fminsearch} accepts the options:
@qcode{"Display"}, @qcode{"FunValCheck"},@qcode{"MaxFunEvals"},
@qcode{"MaxIter"}, @qcode{"OutputFcn"}, @qcode{"TolFun"}, @qcode{"TolX"}.

@qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
before optimization is halted.  The default value is
@code{200 * number_of_variables}, i.e., @code{200 * length (@var{x0})}.
The value must be a positive integer.

@qcode{"MaxIter"} proscribes the maximum number of algorithm iterations
before optimization is halted.  The default value is
@code{200 * number_of_variables}, i.e., @code{200 * length (@var{x0})}.
The value must be a positive integer.

For a description of the other options,
@pxref{XREFoptimset,,@code{optimset}}.  To initialize an options structure
with default values for @code{fminsearch} use
@code{options = optimset ("fminsearch")}.

@code{fminsearch} may also be called with a single structure argument
with the following fields:

@table @code
@item objective
The objective function.

@item x0
The initial point.

@item solver
Must be set to @qcode{"fminsearch"}.

@item options
A structure returned from @code{optimset} or an empty matrix to
indicate that defaults should be used.
@end table

@noindent
The field @code{options} is optional.  All others are required.

On exit, the function returns @var{x}, the minimum point, and @var{fval},
the function value at the minimum.

The third output @var{exitflag} reports whether the algorithm succeeded and
may take one of the following values:

@table @asis
@item 1
if the algorithm converged
(size of the simplex is smaller than @code{TolX} @strong{AND} the step in
function value between iterations is smaller than @code{TolFun}).

@item 0
if the maximum number of iterations or the maximum number of function
evaluations are exceeded.

@item -1
if the iteration is stopped by the @qcode{"OutputFcn"}.
@end table

The fourth output is a structure @var{output} containing runtime
about the algorithm.  Fields in the structure are @code{funcCount}
containing the number of function calls to @var{fcn}, @code{iterations}
containing the number of iteration steps, @code{algorithm} with the name of
the search algorithm (always:
@nospell{@qcode{"Nelder-Mead simplex direct search"}}), and @code{message}
with the exit message.

Example:

@example
fminsearch (@@(x) (x(1)-5).^2+(x(2)-8).^4, [0;0])
@end example

Application Notes:
@enumerate
@item
If you need to find the minimum of a single variable function it is
probably better to use @code{fminbnd}.

@item
The legacy, undocumented syntax for passing parameters to @var{fcn} by
appending them to the input argument list after @var{options} has been
removed in Octave 10.  The cross-platform compatible method of passing
parameters to @var{fcn} is through use of @ref{Anonymous Functions}.  For
specific examples of doing so for @code{fminsearch} and other minimization
functions see the @ref{Minimizers} section of the GNU Octave manual.
@end enumerate
@xseealso{@ref{XREFfminbnd,,fminbnd}, @ref{XREFfminunc,,fminunc}, @ref{XREFoptimset,,optimset}}
@end deftypefn


Certain minimization operations require additional parameters be passed to
the function, @code{F}, being minimized.  E.g., @w{@code{F = F(x, C)}}.
Octave's minimizer functions are designed to only pass one optimization
variable to @code{F}, but parameter passing can be accomplished by defining
an @ref{Anonymous Functions,,Anonymous Function} that contains the necessary
parameter(s).  See the example below:

@example
@group
A = 2; B = 3;
f = @@(x) sin (A*x + B);
fminbnd (f, 0, 2)
   @result{}   0.8562
@end group
@end example

Note that anonymous functions retain the value of parameters at the time they
are defined.  Changing a parameter value after function definition will not
affect output of the function until it is redefined:

@example
@group
B = 4;
fminbnd (f, 0, 2)
   @result{}   0.8562
f = @@(x) sin (A*x + B);
fminbnd (f, 0, 2)
   @result{}   0.3562
@end group
@end example

The function @code{humps} is a useful function for testing zero and
extrema finding functions.

@c humps scripts/optimization/humps.m
@anchor{XREFhumps}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{y} =} humps (@var{x})
@deftypefnx {} {[@var{x}, @var{y}] =} humps (@var{x})
Evaluate a function with multiple minima, maxima, and zero crossings.

The output @var{y} is the evaluation of the rational function:
@tex
$$y = -{ {1200x^4 - 2880x^3 + 2036x^2 - 348x - 88} \over {200x^4 - 480x^3 + 406x^2 - 138x + 17} }$$
@end tex
@ifnottex

@example
@group
        1200*@var{x}^4 - 2880*@var{x}^3 + 2036*@var{x}^2 - 348*@var{x} - 88
 @var{y} = - ---------------------------------------------
         200*@var{x}^4 - 480*@var{x}^3 + 406*@var{x}^2 - 138*@var{x} + 17
@end group
@end example

@end ifnottex

@var{x} may be a scalar, vector or array.  If @var{x} is omitted, the
default range [0:0.05:1] is used.

When called with two output arguments, [@var{x}, @var{y}], @var{x} will
contain the input values, and @var{y} will contain the output from
@code{humps}.

Programming Notes: @code{humps} has two local maxima located near @var{x} =
0.300 and 0.893, a local minimum near @var{x} = 0.637, and zeros near
@var{x} = -0.132 and 1.300.  @code{humps} is a useful function for testing
algorithms which find zeros or local minima and maxima.

Try @code{demo humps} to see a plot of the @code{humps} function.
@xseealso{@ref{XREFfzero,,fzero}, @ref{XREFfminbnd,,fminbnd}, @ref{XREFfminunc,,fminunc}, @ref{XREFfminsearch,,fminsearch}}
@end deftypefn