* Bug 16145 fixed: intg() integrate() intc() default atol
[scilab.git] / scilab / modules / differential_equations / help / pt_BR / 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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  * Copyright (C) 2020 - Samuel GOUGEON
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org" xml:id="intg" xml:lang="pt">
21     <refnamediv>
22         <refname>intg</refname>
23         <refpurpose>integral definida</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Seqüência de Chamamento</title>
27         <synopsis>
28             [v, err] = intg(a, b, f)
29             [v, err] = intg(a, b, f, atol)
30             [v, err] = intg(a, b, f, atol, rtol)
31             [v, err, ierr] = intg(..)
32         </synopsis>
33     </refsynopsisdiv>
34     <refsection>
35         <title>Parâmetros</title>
36         <variablelist>
37             <varlistentry>
38                 <term>a, b</term>
39                 <listitem>
40                     Números reais finitos: limites da integral.
41                     <para/>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>f</term>
46                 <listitem>
47                     função externa (função, lista ou string)
48                     <para/>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>atol</term>
53                 <listitem>
54                     Número real: erro absoluto requerido no resultado. Valor padrão: 1.d-13.
55                     <para/>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>rtol</term>
60                 <listitem>
61                     Número real: erro relativo requerido no resultado. Valor padrão: 1.d-8.
62                     <para/>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>err</term>
67                 <listitem>
68                     erro absoluto estimado no resultado
69                     <para/>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>ierr</term>
74                 <listitem>
75                       error flag number (= 0 if no error occurred).
76                       <para/>
77                 </listitem>
78             </varlistentry>
79         </variablelist>
80     </refsection>
81     <refsection>
82         <title>Descrição</title>
83         <para>
84             <literal>intg(a,b,f)</literal> avalia a integral definida de
85             <literal>a</literal> a <literal>b</literal> de <literal>f(t)dt</literal>.
86             A função <literal>f(t)</literal> deve ser contínua.
87         </para>
88         <para>Espera-se que a avaliação satisfaça à seguinte precisão:
89             <literal>abs(I-v)&lt;= max(atol,er*abs(I))</literal> onde I é o valor exato
90             da integral.
91         </para>
92         <para>
93             <literal>f</literal> é uma função externa :
94         </para>
95         <para>
96             Se <literal>f</literal> é uma função, sua definição deve ser como
97             segue: <literal> y = f(t) </literal>
98         </para>
99         <para>
100             Se <literal>f</literal> é uma lista, a lista deve ser como segue:
101             <literal> list(f,x1,x2,...)</literal> onde <literal>f</literal> é uma
102             função com seqüência de chamamento
103             <literal>f(t,x1,x2,...)</literal>.
104         </para>
105         <para>
106             Se <literal>f</literal> é um string, ele se refere ao nome de uma
107             função FORTRAN ou procedure C com dada seqüência de chamamento:
108         </para>
109         <para>
110             No caso FORTRAN, a seqüência de chamamento deve ser
111             <literal>double precision function f(x)</literal>
112             onde <literal>x</literal> tabém é um número de dupla precisão.
113         </para>
114         <para>
115             No caso C, a seqüência de chamamento é <literal>double f(double *x)</literal>.
116         </para>
117         <para>
118             <emphasis role="bold">Funções Utilizadas</emphasis> :
119             As rotinas associadas (dqags.f e dqagse.f de quadpack) podem ser encontradas
120             no diretório SCI/modules/differential_equations/src/fortran.
121         </para>
122     </refsection>
123     <refsection>
124         <title>Known Limitation</title>
125         <para>
126             Like all the integrators, <literal>intg</literal> is subject to spike missing.
127         </para>
128         <para>
129             A flat function with a spike will be seen as a fully flat function
130             if the spike is stiff enough.
131         </para>
132         <para>
133             This cannot be bypassed. It is easy to understand why when we know how the integrator operates.
134             Indeed, <literal>intg</literal> uses the 21-point Gauss-Kronrod rule.
135             Hence, any spike in-between two consecutive integration points will be undetected,
136             and the function will be considered smooth.
137         </para>
138         <para>
139             However, a warning message will be issued if the function is considered very smooth.
140             The user will then be suggested to reduce the integration interval,
141             should he think that spikes were missed.
142         </para>
143         <para>
144             The following graphs illustrate that phenomenon:
145         </para>
146         <scilab:image localized="true">
147             x = 0:.1:22;
148             y = zeros(1,221); y(1) = 3; y(96) = 1;
149             subplot(1,2,1)
150             plot(x, y, "r");
151             title(_("Unsampled Spike => missed by intg()"), "fontsize",3);
152             xlabel(_("Indices of integration points, as seen by intg()"))
153
154             x = 0:21;
155             y = zeros(1,22); y(1) = 3; y(10) = 1;
156             subplot(1,2,2)
157             plot(x, y, "r");
158             title(_("Sampled spike => detected by intg()"), "fontsize",3);
159             xlabel(_("Indices of integration points, as seen by intg()"))
160
161             gcf().axes_size = [700 350];
162         </scilab:image>
163         <para>
164             On the left image, the spike lays between the 9th and 10th integration points,
165             and is not detected. <literal>intg</literal> considers the function flat.
166             On the right, the spike is large enough to be covered by the integration points.
167         </para>
168         <note>
169             When we want to display the computed solution even if the solver has encountered an error,
170             we should add the third output argument <literal>ierr</literal>. Then errors become
171             simple warnings. This is mostly used in the case of rounding errors.
172         </note>
173     </refsection>
174     <refsection>
175         <title>Exemplos</title>
176         <programlisting role="example"><![CDATA[
177 // caso de função Scilab
178 function y = f(x), y = x*sin(30*x)/sqrt(1-((x/(2*%pi))^2)), endfunction
179 exact = -2.5432596188;
180 I = intg(0, 2*%pi, f)
181 abs(exact - I)
182
183 // caso de função Scilab com parâmetros
184 function y = f1(x,w), y = x*sin(w*x)/sqrt(1-((x/(2*%pi))^2)), endfunction
185 I = intg(0, 2*%pi, list(f1,30))
186 abs(exact - I)
187
188 // caso de código FORTRAN (compilador FORTRAN requerido)
189 // escreve o código FORTRAN
190 cd TMPDIR;
191 F=['      double precision function ffun(x)'
192    '      double precision x,pi'
193    '      pi=3.14159265358979312d+0'
194    '      ffun=x*sin(30.0d+0*x)/sqrt(1.0d+0-(x/(2.0d+0*pi))**2)'
195    '      return'
196    '      end'];
197 mputl(F, 'ffun.f')
198
199 // compile o código FORTRAN
200 l = ilib_for_link('ffun', 'ffun.f', [], 'f');
201
202 // linking incremental
203 link(l, 'ffun', 'f')
204
205 // integrando a função
206 I = intg(0, 2*%pi, 'ffun')
207 abs(exact - I)
208
209 // caso de código C (compilador C requerido)
210 // escreva o código C
211 C=['#include <math.h>'
212    'double cfun(double *x)'
213    '{'
214    '  double y,pi=3.14159265358979312;'
215    '  y=*x/(2.0e0*pi);'
216    '  return *x*sin(30.0e0**x)/sqrt(1.0e0-y*y);'
217    '}'];
218 mputl(C, 'cfun.c')
219
220 // compile o código C
221 l = ilib_for_link('cfun', 'cfun.c', [], 'c');
222
223 // linking incremental
224 link(l, 'cfun', 'c')
225
226 //integrando a função
227 I = intg(0, 2*%pi, 'cfun')
228 abs(exact - I)
229  ]]></programlisting>
230     </refsection>
231     <refsection role="see also">
232         <title>Ver Também</title>
233         <simplelist type="inline">
234             <member>
235                 <link linkend="intc">intc</link>
236             </member>
237             <member>
238                 <link linkend="intl">intl</link>
239             </member>
240             <member>
241                 <link linkend="inttrap">inttrap</link>
242             </member>
243             <member>
244                 <link linkend="intsplin">intsplin</link>
245             </member>
246             <member>
247                 <link linkend="ode">ode</link>
248             </member>
249         </simplelist>
250     </refsection>
251     <refsection role="history">
252         <title>Histórico</title>
253         <revhistory>
254             <revision>
255                 <revnumber>6.0.2</revnumber>
256                 <revdescription>
257                     The default value atol of the absolute tolerance is increased from
258                     10<superscript>-14</superscript> to 10<superscript>-13</superscript>.
259                 </revdescription>
260             </revision>
261         </revhistory>
262     </refsection>
263 </refentry>