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