Nonlinear equations chapter

[Søren Hauberg]

Hi,
  Attached is a minor patch that extends the example in the non-linear 
equations, to also show how to use Jacobians. I think David recently 
mentioned that this chapter and the optimization chapter should be 
merged. Personally I don't agree with that, so I didn't attempt to do this.

Søren

2007-08-29  Søren Hauberg  <address@hidden>

        * doc/interpreter/nonlin.txi: Extended the example.

Index: doc/interpreter/nonlin.txi
===================================================================
RCS file: /cvs/octave/doc/interpreter/nonlin.txi,v
retrieving revision 1.4
diff -u -r1.4 nonlin.txi
--- doc/interpreter/nonlin.txi  18 Jul 2007 17:03:11 -0000      1.4
+++ doc/interpreter/nonlin.txi  29 Aug 2007 19:19:52 -0000
@@ -15,16 +15,18 @@
 $$
 @end tex
 @end iftex
address@hidden
address@hidden
 
 @example
 F (x) = 0
 @end example
address@hidden ifinfo
address@hidden ifnottex
 
 @noindent
 using the function @code{fsolve}, which is based on the @sc{Minpack}
-subroutine @code{hybrd}.
+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.
 
 @DOCSTRING(fsolve)
 
@@ -63,7 +65,7 @@
 @code{f} defined above,
 
 @example
-[x, info] = fsolve ("f", [1; 2])
+[x, info] = fsolve (@@f, [1; 2])
 @end example
 
 @noindent
@@ -78,6 +80,7 @@
 info = 1
 @end example
 
address@hidden
 A value of @code{info = 1} indicates that the solution has converged.
 
 The function @code{perror} may be used to print English messages
@@ -90,4 +93,43 @@
 @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
+
address@hidden
address@hidden
+$$
+\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]
+$$
address@hidden tex
+which is computed with the following Octave function
address@hidden iftex
+
address@hidden
+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
address@hidden example
+
address@hidden
+Using this Jacobian is done with the following code
+
address@hidden
+[x, info] = fsolve (@{@@f, @@address@hidden, [1; 2]);
address@hidden example
+
address@hidden
+which gives the same solution as before.