[doc] Misc. small improvements
[scilab.git] / scilab / modules / differential_equations / help / en_US / int2d.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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
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="int2d" xml:lang="en">
21     <refnamediv>
22         <refname>int2d</refname>
23         <refpurpose>definite 2D integral by quadrature and cubature
24             method
25         </refpurpose>
26     </refnamediv>
27     <refsynopsisdiv>
28         <title>Syntax</title>
29         <synopsis>
30             [I, err] = int2d(X, Y, f)
31             [I, err] = int2d(X, Y, f, params)
32         </synopsis>
33     </refsynopsisdiv>
34     <refsection>
35         <title>Arguments</title>
36         <variablelist>
37             <varlistentry>
38                 <term>X</term>
39                 <listitem>
40                     <para>
41                         a 3 by <literal>N</literal> array containing the abscissae of the vertices of the
42                         N triangles
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>Y</term>
48                 <listitem>
49                     <para>
50                         a 3 by <literal>N</literal> array containing the ordinates of the vertices of the
51                         N triangles
52                     </para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>f</term>
57                 <listitem>
58                     <para>external (function or list or string) defining the integrand
59                         <literal>f(u,v)</literal>
60                     </para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>params</term>
65                 <listitem>
66                     <para>
67                         a real vector <literal>[tol, iclose, maxtri, mevals, iflag]</literal>.
68                         The default value is <literal>[1.d-10, 1, 50, 4000, 1]</literal>.
69                     </para>
70                     <variablelist>
71                         <varlistentry>
72                             <term>tol</term>
73                             <listitem>
74                                 <para>the desired bound on the error. If
75                                     <literal>iflag=0</literal>, <literal>tol</literal> is
76                                     interpreted as a bound on the relative error; if
77                                     <literal>iflag=1</literal>, the bound is on the absolute
78                                     error.
79                                 </para>
80                             </listitem>
81                         </varlistentry>
82                         <varlistentry>
83                             <term>iclose</term>
84                             <listitem>
85                                 <para>an integer parameter that determines the selection of
86                                     LQM0 or LQM1 methods. If <literal>iclose=1</literal> then LQM1
87                                     is used. Any other value of <literal>iclose</literal> causes
88                                     LQM0 to be used. LQM0 uses function values only at interior
89                                     points of the triangle. LQM1 is usually more accurate than
90                                     LQM0 but involves evaluating the integrand at more points
91                                     including some on the boundary of the triangle. It will
92                                     usually be better to use LQM1 unless the integrand has
93                                     singularities on the boundary of the triangle.
94                                 </para>
95                             </listitem>
96                         </varlistentry>
97                         <varlistentry>
98                             <term>maxtri</term>
99                             <listitem>
100                                 <para>the maximum number of triangles in the final
101                                     triangulation of the region
102                                 </para>
103                             </listitem>
104                         </varlistentry>
105                         <varlistentry>
106                             <term>mevals</term>
107                             <listitem>
108                                 <para>the maximum number of function evaluations to be
109                                     allowed. This number will be effective in limiting the
110                                     computation only if it is less than
111                                     94*<literal>maxtri</literal> when LQM1 is specified or
112                                     56*<literal>maxtri</literal> when LQM0 is specified.
113                                 </para>
114                             </listitem>
115                         </varlistentry>
116                         <varlistentry>
117                             <term>iflag</term>
118                             <listitem>
119                                 <para>
120                                     if <literal>iflag=0</literal>, <literal>tol</literal> is
121                                     interpreted as a bound on the relative error; if <literal>iflag=1</literal>,
122                                     the bound is on the absolute error.
123                                 </para>
124                             </listitem>
125                         </varlistentry>
126                     </variablelist>
127                 </listitem>
128             </varlistentry>
129             <varlistentry>
130                 <term>I</term>
131                 <listitem>
132                     <para>the integral value</para>
133                 </listitem>
134             </varlistentry>
135             <varlistentry>
136                 <term>err</term>
137                 <listitem>
138                     <para>the estimated error</para>
139                 </listitem>
140             </varlistentry>
141         </variablelist>
142     </refsection>
143     <refsection>
144         <title>Description</title>
145         <para>
146             <literal>int2d</literal> computes the two-dimensional integral of a
147             function <literal>f</literal> over a region consisting of
148             <literal>n</literal> triangles. A total error estimate is obtained and
149             compared with a tolerance - <literal>tol</literal> - that is provided as
150             input to the subroutine. The error tolerance is treated as either relative
151             or absolute depending on the input value of <literal>iflag</literal>. A
152             'Local Quadrature Module' is applied to each input triangle and estimates
153             of the total integral and the total error are computed. The local
154             quadrature module is either subroutine LQM0 or subroutine LQM1 and the
155             choice between them is determined by the value of the input variable
156             <literal>iclose</literal>.
157         </para>
158         <para>If the total error estimate exceeds the tolerance, the triangle with
159             the largest absolute error is divided into two triangles by a median to
160             its longest side. The local quadrature module is then applied to each of
161             the subtriangles to obtain new estimates of the integral and the error.
162             This process is repeated until either (1) the error tolerance is
163             satisfied, (2) the number of triangles generated exceeds the input
164             parameter <literal>maxtri</literal>, (3) the number of integrand
165             evaluations exceeds the input parameter <literal>mevals</literal>, or (4)
166             the function senses that roundoff error is beginning to contaminate the
167             result.
168         </para>
169     </refsection>
170     <refsection>
171         <title>Examples</title>
172         <programlisting role="example"><![CDATA[
173 X = [0,0;1,1;1,0];
174 Y = [0,0;0,1;1,1];
175 deff('z=f(x,y)','z=cos(x+y)')
176 [I,e] = int2d(X,Y,f)
177 // computes the integrand over the square [0 1]x[0 1]
178  ]]></programlisting>
179     </refsection>
180     <refsection role="see also">
181         <title>See also</title>
182         <simplelist type="inline">
183             <member>
184                 <link linkend="mesh2d">mesh2d</link>
185             </member>
186             <member>
187                 <link linkend="int3d">int3d</link>
188             </member>
189             <member>
190                 <link linkend="intg">intg</link>
191             </member>
192             <member>
193                 <link linkend="intl">intl</link>
194             </member>
195             <member>
196                 <link linkend="intc">intc</link>
197             </member>
198         </simplelist>
199     </refsection>
200 </refentry>