@c Copyright (C) 1996-2012 John W. Eaton
@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 the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c 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 <http://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.

@DOCSTRING(fsolve)

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.

@DOCSTRING(fzero)

@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

@DOCSTRING(fminbnd)

@DOCSTRING(fminunc)

@DOCSTRING(fminsearch)