c89b57067941a2eecc4f9ee00328a6687ee2bca1
[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]=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         </variablelist>
67     </refsection>
68     <refsection>
69         <title>Description</title>
70         <para>
71             <literal>intg(a,b,f)</literal> evaluates the definite integral from
72             <literal>a</literal> to <literal>b</literal> of <literal>f(t)dt</literal>.
73             The function <literal>f(t)</literal> should be continuous.
74         </para>
75         <para>The evaluation hopefully satisfies following claim for accuracy:
76             <literal>abs(I-v)&lt;= max(ea,er*abs(I))</literal> where
77             <literal>I</literal> stands for the exact value of the integral.
78         </para>
79         <para>
80             <literal>f</literal> is an external :
81         </para>
82         <para>
83             If <literal>f</literal> is function its definition must be as
84             follows <literal> y = f(t) </literal>
85         </para>
86         <para>
87             If <literal>f</literal> is a list the list must be as follows:
88             <literal> list(f,x1,x2,...)</literal> where <literal>f</literal> is a
89             function with calling sequence <literal>f(t,x1,x2,...)</literal>.
90         </para>
91         <para>
92             If <literal>f</literal> is a string it refers to the name of a
93             Fortran function or a C prodedure with a given calling sequence:
94         </para>
95         <para>
96             In the fortran case the calling sequence should be <literal>double
97                 precision function f(x)
98             </literal>
99             where <literal>x</literal> is also a
100             double precision number.
101         </para>
102         <para>
103             In the C case the calling sequence should be <literal>double
104                 f(double *x)
105             </literal>
106             .
107         </para>
108     </refsection>
109     <refsection>
110         <title>Examples</title>
111         <programlisting role="example"><![CDATA[ 
112 // Function written in the Scilab language
113 function y=f(x),y=x*sin(30*x)/sqrt(1-((x/(2*%pi))^2)),endfunction
114 exact=-2.5432596188;
115 I=intg(0,2*%pi,f)
116 abs(exact-I)
117
118 // Function with an argument written in the Scilab language
119 function y=f1(x,w),y=x*sin(w*x)/sqrt(1-((x/(2*%pi))^2)),endfunction
120 I=intg(0,2*%pi,list(f1,30))
121 abs(exact-I)
122
123
124 // Function written in Fortran (a Fortran compiler is required)
125 // define a Fortran function
126 cd TMPDIR;
127 F=['      double precision function ffun(x)'
128    '      double precision x,pi'
129    '      pi=3.14159265358979312d+0'
130    '      ffun=x*sin(30.0d+0*x)/sqrt(1.0d+0-(x/(2.0d+0*pi))**2)'
131    '      return'
132    '      end'];
133 mputl(F,fullfile(TMPDIR,'ffun.f'))
134
135 // compile the function
136 l=ilib_for_link('ffun',fullfile(TMPDIR,'ffun.f'),[],'f');
137
138 // add the function to the working environment
139 link(l,'ffun','f')
140
141 // integrate the function
142 I=intg(0,2*%pi,'ffun')
143 abs(exact-I)
144
145 // Function written in C (a C compiler is required)
146 // define a C function
147 C=['#include <math.h>'
148    'double cfun(double *x)'
149    '{'
150    '  double y,pi=3.14159265358979312;'
151    '  y=*x/(2.0e0*pi);'
152    '  return *x*sin(30.0e0**x)/sqrt(1.0e0-y*y);'
153    '}'];
154 mputl(C,fullfile(TMPDIR,'cfun.c'))
155
156 // compile the function
157 l=ilib_for_link('cfun',fullfile(TMPDIR,'cfun.c'),[],'c');
158
159 // add the function to the working environment
160 link(l,'cfun','c')
161
162 // integrate the function
163 I=intg(0,2*%pi,'cfun')
164 abs(exact-I)
165  ]]></programlisting>
166     </refsection>
167     <refsection role="see also">
168         <title>See Also</title>
169         <simplelist type="inline">
170             <member>
171                 <link linkend="intc">intc</link>
172             </member>
173             <member>
174                 <link linkend="intl">intl</link>
175             </member>
176             <member>
177                 <link linkend="inttrap">inttrap</link>
178             </member>
179             <member>
180                 <link linkend="intsplin">intsplin</link>
181             </member>
182             <member>
183                 <link linkend="ode">ode</link>
184             </member>
185         </simplelist>
186     </refsection>
187     <refsection>
188         <title>Used Functions</title>
189         <para>The associated routines can be found in SCI/modules/differential_equations/src/fortran directory
190             :
191         </para>
192         <para>dqag0.f and dqags.f from quadpack</para>
193     </refsection>
194 </refentry>