* Bugs #5728 10229 invalid - Differential_equations: Quadpack update
[scilab.git] / scilab / modules / differential_equations / help / en_US / intg.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  * 
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-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:ns5="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="intg" xml:lang="en">
15     <refnamediv>
16         <refname>intg</refname>
17         <refpurpose>definite integral</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>[v,err [,ierr]]=intg(a,b,f [,ea [,er])</synopsis>
22     </refsynopsisdiv>
23     <refsection>
24         <title>Arguments</title>
25         <variablelist>
26             <varlistentry>
27                 <term>a, b</term>
28                 <listitem>
29                     <para>real numbers.</para>
30                 </listitem>
31             </varlistentry>
32             <varlistentry>
33                 <term>f</term>
34                 <listitem>
35                     <para>external (function or list or string).</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>ea, er</term>
40                 <listitem>
41                     <para>real numbers.</para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>ea</term>
46                 <listitem>
47                     <para>absolute error required on the result. Default value:
48                         1.d-14.
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>er</term>
54                 <listitem>
55                     <para>relative error required on the result. Default value:
56                         1.d-8.
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>err</term>
62                 <listitem>
63                     <para>estimated absolute error on the result.</para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>ierr</term>
68                 <listitem>
69                     <para>error flag number (= 0 if no error occured).</para>
70                 </listitem>
71             </varlistentry>
72         </variablelist>
73     </refsection>
74     <refsection>
75         <title>Description</title>
76         <para>
77             <literal>intg(a,b,f)</literal> evaluates the definite integral from
78             <literal>a</literal> to <literal>b</literal> of <literal>f(t)dt</literal>.
79             The function <literal>f(t)</literal> should be continuous.
80         </para>
81         <para>The evaluation hopefully satisfies following claim for accuracy:
82             <literal>abs(I-v)&lt;= max(ea,er*abs(I))</literal> where
83             <literal>I</literal> stands for the exact value of the integral.
84         </para>
85         <para>
86             <literal>f</literal> is an external :
87         </para>
88         <para>
89             If <literal>f</literal> is function its definition must be as
90             follows <literal> y = f(t) </literal>
91         </para>
92         <para>
93             If <literal>f</literal> is a list the list must be as follows:
94             <literal> list(f,x1,x2,...)</literal> where <literal>f</literal> is a
95             function with calling sequence <literal>f(t,x1,x2,...)</literal>.
96         </para>
97         <para>
98             If <literal>f</literal> is a string it refers to the name of a
99             Fortran function or a C prodedure with a given calling sequence:
100         </para>
101         <para>
102             In the fortran case the calling sequence should be <literal>double
103                 precision function f(x)
104             </literal>
105             where <literal>x</literal> is also a
106             double precision number.
107         </para>
108         <para>
109             In the C case the calling sequence should be <literal>double
110                 f(double *x)
111             </literal>
112             .
113         </para>
114     </refsection>
115     <refsection>
116         <title>Known Limitation</title>
117         <para>
118             Like all the integrators, <literal>intg</literal> is subject to spike missing.
119         </para>
120         <para>
121             A flat function with a spike will be seen as a fully flat function
122             if the spike is stiff enough.
123         </para>
124         <para>
125             This cannot be bypassed, it is easy to understand why when we know how the integrator operates.
126             Indeed, <literal>intg</literal> uses the 21-point Gauss-Kronrod rule,
127             so if there is a spike in-between two consecutive integration points,
128             then it will go undetected, the function will be considered smooth.
129         </para>
130         <para>
131             However, a warning message will be issued if the function is considered very smooth.
132             The user will then be suggested to reduce the integration interval,
133             should he think that spikes were missed.
134         </para>
135         <para>
136             The following graphs illustrate that phenomenon.
137         </para>
138         <scilab:image>
139             x = 0:.1:22;
140             y = zeros(1,221); y(1) = 3; y(96) = 1;
141             plot(x, y);
142             xtitle("Spike missed");
143         </scilab:image>
144         <para>
145             Being in-between the 9th and 10th integration points,
146             that spike is not detected and
147             <literal>intg</literal> considers the function flat.
148             In the next image, the spike is large enough to be covered by the integration points.
149         </para>
150         <scilab:image>
151             x = 0:21;
152             y = zeros(1,22); y(1) = 3; y(10) = 1;
153             plot(x, y);
154             xtitle("Spike detected");
155         </scilab:image>
156         <para>
157             If the user wants to display the computed solution even if the solver has encountered an error,
158             he should add the third output argument <literal>ierr</literal>, that will transform the
159             errors into warnings. This is mostly used in the case of rounding errors.
160         </para>
161     </refsection>
162     <refsection>
163         <title>Examples</title>
164         <programlisting role="example"><![CDATA[ 
165 // Function written in the Scilab language
166 function y=f(x),y=x*sin(30*x)/sqrt(1-((x/(2*%pi))^2)),endfunction
167 exact=-2.5432596188;
168 I=intg(0,2*%pi,f)
169 abs(exact-I)
170
171 // Function with an argument written in the Scilab language
172 function y=f1(x,w),y=x*sin(w*x)/sqrt(1-((x/(2*%pi))^2)),endfunction
173 I=intg(0,2*%pi,list(f1,30))
174 abs(exact-I)
175
176
177 // Function written in Fortran (a Fortran compiler is required)
178 // define a Fortran function
179 cd TMPDIR;
180 F=['      double precision function ffun(x)'
181    '      double precision x,pi'
182    '      pi=3.14159265358979312d+0'
183    '      ffun=x*sin(30.0d+0*x)/sqrt(1.0d+0-(x/(2.0d+0*pi))**2)'
184    '      return'
185    '      end'];
186 mputl(F,fullfile(TMPDIR,'ffun.f'))
187
188 // compile the function
189 l=ilib_for_link('ffun',fullfile(TMPDIR,'ffun.f'),[],'f');
190
191 // add the function to the working environment
192 link(l,'ffun','f')
193
194 // integrate the function
195 I=intg(0,2*%pi,'ffun')
196 abs(exact-I)
197
198 // Function written in C (a C compiler is required)
199 // define a C function
200 C=['#include <math.h>'
201    'double cfun(double *x)'
202    '{'
203    '  double y,pi=3.14159265358979312;'
204    '  y=*x/(2.0e0*pi);'
205    '  return *x*sin(30.0e0**x)/sqrt(1.0e0-y*y);'
206    '}'];
207 mputl(C,fullfile(TMPDIR,'cfun.c'))
208
209 // compile the function
210 l=ilib_for_link('cfun',fullfile(TMPDIR,'cfun.c'),[],'c');
211
212 // add the function to the working environment
213 link(l,'cfun','c')
214
215 // integrate the function
216 I=intg(0,2*%pi,'cfun')
217 abs(exact-I)
218  ]]></programlisting>
219     </refsection>
220     <refsection role="see also">
221         <title>See Also</title>
222         <simplelist type="inline">
223             <member>
224                 <link linkend="intc">intc</link>
225             </member>
226             <member>
227                 <link linkend="intl">intl</link>
228             </member>
229             <member>
230                 <link linkend="inttrap">inttrap</link>
231             </member>
232             <member>
233                 <link linkend="intsplin">intsplin</link>
234             </member>
235             <member>
236                 <link linkend="ode">ode</link>
237             </member>
238         </simplelist>
239     </refsection>
240     <refsection>
241         <title>Used Functions</title>
242         <para>The associated routines can be found in SCI/modules/differential_equations/src/fortran directory
243             :
244         </para>
245         <para>dqags.f and dqagse.f from quadpack</para>
246     </refsection>
247 </refentry>