* Bug 16145 fixed: intg() integrate() intc() default atol
[scilab.git] / scilab / modules / differential_equations / help / en_US / integrate.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) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2020 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:id="integrate" xml:lang="en">
20     <refnamediv>
21         <refname>integrate</refname>
22         <refpurpose>integration of an expression by quadrature</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27            y = integrate(expr, v, x0, x1)
28            y = integrate(expr, v, x0, x1, atol)
29            y = integrate(expr, v, x0, x1, atol, rtol)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>expr</term>
37                 <listitem>
38                     a character string defining a Scilab expression.
39                     <para/>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>v</term>
44                 <listitem>
45                     a character string, the integration variable name.
46                     <para/>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>x0</term>
51                 <listitem>
52                     a real number, the lower bound of integration.
53                     <para/>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>x1</term>
58                 <listitem>
59                     a vector of real numbers, upper bounds of integration.
60                     <para/>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>atol</term>
65                 <listitem>
66                     a real number (absolute error bound). Default value: 1e-13.
67                     <para/>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>rtol</term>
72                 <listitem>
73                     a real number, (relative error bound). Default value: 1e-8.
74                     <para/>
75                 </listitem>
76             </varlistentry>
77             <varlistentry>
78                 <term>y</term>
79                 <listitem>
80                     a vector of real numbers, the integral value for each <literal>x1(i)</literal>.
81                     <para/>
82                 </listitem>
83             </varlistentry>
84         </variablelist>
85     </refsection>
86     <refsection>
87         <title>Description</title>
88         <para>
89             <literal>y = integrate(expr, v, x0, x1 [,atol [,rtol]])</literal> computes
90             <latex alt="y(i) = integral_{x_0}^{x_1(i)} f(v).dv">
91                 y(i) = \int_{x_0}^{x_1(i)} f(v)\,dv
92             </latex>
93             for <literal>i=1:size(x1,'*')</literal>, where <emphasis>f(v)</emphasis>
94             is given by the expression <literal>expr</literal>.
95         </para>
96         <para>The evaluation hopefully satisfies following claim for accuracy:
97             <literal>abs(I - y) &lt;= max(atol, rtol*abs(I))</literal> where
98             <literal>I</literal> stands for the exact value of the integral.
99         </para>
100         <para>
101             <warning>
102                 Restriction: The given expression must not use variable names with a leading
103                 <literal>%</literal>.
104             </warning>
105         </para>
106     </refsection>
107     <refsection>
108         <title>Examples</title>
109         <programlisting role="example"><![CDATA[
110 x1 = 0:0.1:2*%pi;
111 Y = integrate('sin(x)', 'x', 0, x1);
112 norm(cos(x1)-(1-Y))
113
114 x1 = -10:0.1:10;
115 Y = integrate(['if x==0 then 1,';
116                'else sin(x)/x,end'], 'x', 0, x1)
117  ]]></programlisting>
118     </refsection>
119     <refsection role="see also">
120         <title>See also</title>
121         <simplelist type="inline">
122             <member>
123                 <link linkend="intg">intg</link>
124             </member>
125             <member>
126                 <link linkend="inttrap">inttrap</link>
127             </member>
128             <member>
129                 <link linkend="intsplin">intsplin</link>
130             </member>
131             <member>
132                 <link linkend="ode">ode</link>
133             </member>
134         </simplelist>
135     </refsection>
136     <refsection role="history">
137         <title>History</title>
138         <revhistory>
139             <revision>
140                 <revnumber>6.1.0</revnumber>
141                 <revdescription>
142                     Default atol value increased from
143                     10<superscript>-14</superscript> to 10<superscript>-13</superscript>.
144                 </revdescription>
145             </revision>
146         </revhistory>
147     </refsection>
148 </refentry>