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>