f5a083ae74d80e9f35f9618003f3eda082afef37
[scilab.git] / scilab / modules / optimization / help / en_US / fsolve.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * Copyright (C) 2011 - DIGITEO - Michael Baudin
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="fsolve" xml:lang="en">
15     <refnamediv>
16         <refname>fsolve</refname>
17         <refpurpose>find a zero of a system of n nonlinear functions</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>[x [,v [,info]]]=fsolve(x0,fct [,fjac] [,tol])</synopsis>
22     </refsynopsisdiv>
23     <refsection>
24         <title>Arguments</title>
25         <variablelist>
26             <varlistentry>
27                 <term>x0</term>
28                 <listitem>
29                     <para>real vector (initial value of function argument).</para>
30                 </listitem>
31             </varlistentry>
32             <varlistentry>
33                 <term>fct</term>
34                 <listitem>
35                     <para>external (i.e function or list or string).</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>fjac</term>
40                 <listitem>
41                     <para>external (i.e function or list or string).</para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>tol</term>
46                 <listitem>
47                     <para>real scalar. precision tolerance: termination occurs when the
48                         algorithm estimates that the relative error between x and the
49                         solution is at most tol. (<literal>tol=1.d-10</literal> is the
50                         default value).
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>x :</term>
56                 <listitem>
57                     <para>real vector (final value of function argument, estimated
58                         zero).
59                     </para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>v :</term>
64                 <listitem>
65                     <para>real vector (value of function at x).</para>
66                 </listitem>
67             </varlistentry>
68             <varlistentry>
69                 <term>info</term>
70                 <listitem>
71                     <para>termination indicator</para>
72                     <variablelist>
73                         <varlistentry>
74                             <term>0</term>
75                             <listitem>
76                                 <para>improper input parameters.</para>
77                             </listitem>
78                         </varlistentry>
79                         <varlistentry>
80                             <term>1</term>
81                             <listitem>
82                                 <para>algorithm estimates that the relative error between x
83                                     and the solution is at most tol.
84                                 </para>
85                             </listitem>
86                         </varlistentry>
87                         <varlistentry>
88                             <term>2</term>
89                             <listitem>
90                                 <para>number of calls to fcn reached</para>
91                             </listitem>
92                         </varlistentry>
93                         <varlistentry>
94                             <term>3</term>
95                             <listitem>
96                                 <para>tol is too small. No further improvement in the
97                                     approximate solution x is possible.
98                                 </para>
99                             </listitem>
100                         </varlistentry>
101                         <varlistentry>
102                             <term>4</term>
103                             <listitem>
104                                 <para>iteration is not making good progress.</para>
105                             </listitem>
106                         </varlistentry>
107                     </variablelist>
108                 </listitem>
109             </varlistentry>
110         </variablelist>
111     </refsection>
112     <refsection>
113         <title>Description</title>
114         <para>find a zero of a system of n nonlinear functions in n variables by a
115             modification of the powell hybrid method. Jacobian may be provided.
116         </para>
117         <programlisting role=""><![CDATA[
118 0 = fct(x) w.r.t x.
119  ]]></programlisting>
120         <para>
121             <literal>fct</literal> is an "external". This external returns
122             <literal>v=fct(x)</literal> given <literal>x</literal>.
123         </para>
124         <para>
125             The simplest calling sequence for <literal>fct</literal> is:
126         </para>
127         <programlisting role=""><![CDATA[
128 [v]=fct(x).
129  ]]></programlisting>
130         <para>
131             If <literal>fct</literal> is a character string, it refers to a C or
132             Fortran routine which must be linked to Scilab. Fortran calling sequence
133             must be
134         </para>
135         <programlisting role=""><![CDATA[
136 fct(n,x,v,iflag)
137 integer n,iflag
138 double precision x(n),v(n)
139  ]]></programlisting>
140         <para>and C Calling sequence must be</para>
141         <programlisting role=""><![CDATA[
142 fct(int *n, double x[],double v[],int *iflag)
143  ]]></programlisting>
144         <para>
145             Incremental link is possible (help <literal>link</literal>).
146         </para>
147         <para>
148             <literal>jac</literal> is an "external". This external returns
149             <literal>v=d(fct)/dx (x)</literal> given <literal>x</literal>.
150         </para>
151         <para>
152             The simplest calling sequence for <literal>jac</literal> is:
153         </para>
154         <programlisting role=""><![CDATA[
155 [v]=jac(x).
156  ]]></programlisting>
157         <para>
158             If <literal>jac</literal> is a character string, it refers to a to a
159             C or Fortran routine which must be linked to Scilab calling sequences are
160             the same as those for fct. Note however that v must be a nxn array.
161         </para>
162     </refsection>
163     <refsection>
164         <title>Examples</title>
165         <programlisting role="example"><![CDATA[
166 // A simple example with fsolve
167 a=[1,7;2,8];
168 b=[10;11];
169
170 function y=fsol1(x)
171   y=a*x+b
172 endfunction
173 function y=fsolj1(x)
174   y=a
175 endfunction
176
177 [xres]=fsolve([100;100],fsol1);
178 a*xres+b
179
180 [xres]=fsolve([100;100],fsol1,fsolj1);
181 a*xres+b
182
183 // See SCI/modules/optimization/sci_gateway/fortran/Ex-fsolve.f
184 [xres]=fsolve([100;100],'fsol1','fsolj1',1.e-7);
185 a*xres+b
186  ]]></programlisting>
187         <para>For some starting points and some equations system, the fsolve method can fail. The fsolve method is a local search method.
188             So, to have a good chance to find a solution to your equations system, you must ship, a good starting point to fsolve.
189         </para>
190         <para> Here is an example on which fsolve can fail:</para>
191         <programlisting role="example"><![CDATA[
192 // Another example with fsolve
193 function F=feuler(x,r)
194   F=x-r-dt*(x.^2-x.^3);
195 endfunction
196 function J=dFdx(x)  //definition de la derivee de F
197    J=1-dt*(2*x-3*x^2);
198 endfunction
199
200 r = 0.04257794928862307 ;
201 dt = 10;
202
203 [x,v,info]=fsolve(r,list(feuler,r),dFdx); // fsolve do not find the solution
204 disp(v); // The residual
205 disp(info); // The termination indicator
206
207 [x,v,info]=fsolve(1,list(feuler,r),dFdx); // fsolve find the solution
208 disp(v); // The residual
209 disp(info); // The termination indicator
210
211 clf();
212 x=linspace(0,1,1000);
213 plot(x,feuler(x))
214 a=gca();
215 a.grid=[5 5];
216  ]]></programlisting>
217         <scilab:image>
218             function F=feuler(x,r)
219             F=x-r-dt*(x.^2-x.^3);
220             endfunction
221             function J=dFdx(x)
222             J=1-dt*(2*x-3*x^2);
223             endfunction
224             
225             r = 0.04257794928862307 ;
226             dt = 10;
227             
228             [x,v,info]=fsolve(r,list(feuler,r),dFdx);
229             [x,v,info]=fsolve(1,list(feuler,r),dFdx);
230             x=linspace(0,1,1000);
231             plot(x,feuler(x))
232             a=gca();
233             a.grid=[5 5];
234         </scilab:image>
235         <para>So, each time you use fsolve, be sure to check the termination indicator and the residual value to see if fsolve has converged.</para>
236     </refsection>
237     <refsection role="see also">
238         <title>See Also</title>
239         <simplelist type="inline">
240             <member>
241                 <link linkend="external">external</link>
242             </member>
243             <member>
244                 <link linkend="qpsolve">qpsolve</link>
245             </member>
246             <member>
247                 <link linkend="optim">optim</link>
248             </member>
249         </simplelist>
250     </refsection>
251 </refentry>