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

@c Copyright (C) 1996, 1997, 2007, 2008 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

Octave can solve sets of nonlinear equations of the form
@iftex
@tex
$$
 f (x) = 0
$$
@end tex
@end iftex
@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 will have to be provided.  This also has the consequence that
convergence is not guarantied even if a solution exists.

@anchor{doc-fsolve}
@deftypefn {Loadable Function} {[@var{x}, @var{fval}, @var{info}] =} fsolve (@var{fcn}, @var{x0})
Given @var{fcn}, the name of a function of the form @code{f (@var{x})}
and an initial starting point @var{x0}, @code{fsolve} solves the set of
equations such that @code{f(@var{x}) == 0}.

On return, @var{fval} contains the value of the function @var{fcn}
evaluated at @var{x}, and @var{info} may be one of the following values:

@table @asis

@item -2
Invalid input parameters.
@item -1
Error in user-supplied function.
@item 1
Relative error between two consecutive iterates is at most the
specified tolerance (see @code{fsolve_options}).
@item 3
Algorithm failed to converge.
@item 4
Limit on number of function calls reached.
@end table

If @var{fcn} is a two-element string array, or a two element cell array
containing either the function name or inline or function handle. The
first element names the function @math{f} described above, and the second
element names a function of the form @code{j (@var{x})} to compute the
Jacobian matrix with elements
@tex
$$ J = {\partial f_i \over \partial x_j} $$
@end tex
@ifinfo

@example
           df_i
jac(i,j) = ----
           dx_j
@end example
@end ifinfo

You can use the function @code{fsolve_options} to set optional
parameters for @code{fsolve}.
@end deftypefn


@anchor{doc-fsolve_options}
@deftypefn {Loadable Function} {} fsolve_options (@var{opt}, @var{val})
When called with two arguments, this function allows you set options
parameters for the function @code{fsolve}.  Given one argument,
@code{fsolve_options} returns the value of the corresponding option.  If
no arguments are supplied, the names of all the available options and
their current values are displayed.

Options include

@table @code
@item "tolerance"
Nonnegative relative tolerance.
@end table
@end deftypefn


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

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

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

@example
function y = f (x)
  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 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
x =

  0.57983
  2.54621

fval =

  -5.7184e-10
   5.5460e-10

info = 1
@end example

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

The function @code{perror} may be used to print English messages
corresponding to the numeric error codes.  For example,

@example
@group
perror ("fsolve", 1)
     @print{} solution converged to requested tolerance
@end group
@end example

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
which is computed with the following Octave function
@end iftex

@example
function J = jacobian(x)
  J(1,1) =  3*x(2) - 4*x(1);
  J(1,2) =  4*cos(x(2)) + 3*x(1);
  J(2,1) = -2*x(2)^2 - 3*sin(x(1)) + 6*x(1);
  J(2,2) = -4*x(1)*x(2);
endfunction
@end example

@noindent
Using this Jacobian is done with the following code

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

@noindent
which gives the same solution as before.

