1@c Copyright (C) 1996-2019 John W. Eaton
2@c
3@c This file is part of Octave.
4@c
5@c Octave is free software: you can redistribute it and/or modify it
6@c under the terms of the GNU General Public License as published by
7@c the Free Software Foundation, either version 3 of the License, or
8@c (at your option) any later version.
9@c
10@c Octave is distributed in the hope that it will be useful, but
11@c WITHOUT ANY WARRANTY; without even the implied warranty of
12@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13@c GNU General Public License for more details.
14@c
15@c You should have received a copy of the GNU General Public License
16@c along with Octave; see the file COPYING.  If not, see
17@c <https://www.gnu.org/licenses/>.
18
19@node Nonlinear Equations
20@chapter Nonlinear Equations
21@cindex nonlinear equations
22@cindex equations, nonlinear
23
24@menu
25* Solvers::
26* Minimizers::
27@end menu
28
29@node Solvers
30@section Solvers
31
32Octave can solve sets of nonlinear equations of the form
33@tex
34$$
35 f (x) = 0
36$$
37@end tex
38@ifnottex
39
40@example
41F (x) = 0
42@end example
43
44@end ifnottex
45
46@noindent
47using the function @code{fsolve}, which is based on the @sc{minpack}
48subroutine @code{hybrd}.  This is an iterative technique so a starting
49point must be provided.  This also has the consequence that
50convergence is not guaranteed even if a solution exists.
51
52@DOCSTRING(fsolve)
53
54The following is a complete example.  To solve the set of equations
55@tex
56$$
57 \eqalign{-2x^2 + 3xy + 4\sin(y) - 6 &= 0\cr
58           3x^2 - 2xy^2 + 3\cos(x) + 4 &= 0}
59$$
60@end tex
61@ifnottex
62
63@example
64@group
65-2x^2 + 3xy   + 4 sin(y) = 6
66 3x^2 - 2xy^2 + 3 cos(x) = -4
67@end group
68@end example
69
70@end ifnottex
71
72@noindent
73you first need to write a function to compute the value of the given
74function.  For example:
75
76@example
77@group
78function y = f (x)
79  y = zeros (2, 1);
80  y(1) = -2*x(1)^2 + 3*x(1)*x(2)   + 4*sin(x(2)) - 6;
81  y(2) =  3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4;
82endfunction
83@end group
84@end example
85
86Then, call @code{fsolve} with a specified initial condition to find the
87roots of the system of equations.  For example, given the function
88@code{f} defined above,
89
90@example
91[x, fval, info] = fsolve (@@f, [1; 2])
92@end example
93
94@noindent
95results in the solution
96
97@example
98@group
99x =
100
101  0.57983
102  2.54621
103
104fval =
105
106  -5.7184e-10
107   5.5460e-10
108
109info = 1
110@end group
111@end example
112
113@noindent
114A value of @code{info = 1} indicates that the solution has converged.
115
116When no Jacobian is supplied (as in the example above) it is approximated
117numerically.  This requires more function evaluations, and hence is
118less efficient.  In the example above we could compute the Jacobian
119analytically as
120
121@iftex
122@tex
123$$
124\left[\matrix{ {\partial f_1 \over \partial x_1} &
125               {\partial f_1 \over \partial x_2} \cr
126               {\partial f_2 \over \partial x_1} &
127               {\partial f_2 \over \partial x_2} \cr}\right] =
128\left[\matrix{ 3 x_2 - 4 x_1                  &
129               4 \cos(x_2) + 3 x_1            \cr
130               -2 x_2^2 - 3 \sin(x_1) + 6 x_1 &
131               -4 x_1 x_2                     \cr }\right]
132$$
133@end tex
134and compute it with the following Octave function
135@end iftex
136
137@example
138@group
139function [y, jac] = f (x)
140  y = zeros (2, 1);
141  y(1) = -2*x(1)^2 + 3*x(1)*x(2)   + 4*sin(x(2)) - 6;
142  y(2) =  3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4;
143  if (nargout == 2)
144    jac = zeros (2, 2);
145    jac(1,1) =  3*x(2) - 4*x(1);
146    jac(1,2) =  4*cos(x(2)) + 3*x(1);
147    jac(2,1) = -2*x(2)^2 - 3*sin(x(1)) + 6*x(1);
148    jac(2,2) = -4*x(1)*x(2);
149  endif
150endfunction
151@end group
152@end example
153
154@noindent
155The Jacobian can then be used with the following call to @code{fsolve}:
156
157@example
158[x, fval, info] = fsolve (@@f, [1; 2], optimset ("jacobian", "on"));
159@end example
160
161@noindent
162which gives the same solution as before.
163
164@DOCSTRING(fzero)
165
166@node Minimizers
167@section Minimizers
168@cindex local minimum
169@cindex finding minimums
170
171Often it is useful to find the minimum value of a function rather than just
172the zeroes where it crosses the x-axis.  @code{fminbnd} is designed for the
173simpler, but very common, case of a univariate function where the interval
174to search is bounded.  For unbounded minimization of a function with
175potentially many variables use @code{fminunc} or @code{fminsearch}.  The two
176functions use different internal algorithms and some knowledge of the objective
177function is required.  For functions which can be differentiated,
178@code{fminunc} is appropriate.  For functions with discontinuities, or for
179which a gradient search would fail, use @code{fminsearch}.
180@xref{Optimization}, for minimization with the presence of constraint
181functions.  Note that searches can be made for maxima by simply inverting the
182objective function
183@tex
184($F_{max} = -F_{min}$).
185@end tex
186@ifnottex
187(@code{Fto_max = -Fto_min}).
188@end ifnottex
189
190@DOCSTRING(fminbnd)
191
192@DOCSTRING(fminunc)
193
194@DOCSTRING(fminsearch)
195
196The function @code{humps} is a useful function for testing zero and
197extrema finding functions.
198
199@DOCSTRING(humps)
200