<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * ...
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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="int2d" xml:lang="en">
    <refnamediv>
        <refname>int2d</refname>
        <refpurpose>definite 2D integral by quadrature method
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
          [I, err] = int2d(X, Y, f)
          [I, err] = int2d(X, Y, f, params)
          [I, err] = int2d(xmin, xmax, ymin, ymax, f)
          [I, err] = int2d(xmin, xmax, ymin, ymax, f, params)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>X</term>
                <listitem>
                    <para>
                        a 3 by <literal>N</literal> array containing the abscissae of the vertices of the
                        N triangles
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Y</term>
                <listitem>
                    <para>
                        a 3 by <literal>N</literal> array containing the ordinates of the vertices of the
                        N triangles
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>xmin, xmax, ymin, ymax</term>
                <listitem>
                    <para>
                      real scalars defining a rectangle in the plane
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>f</term>
                <listitem>
                    <para>external (function or list or string) defining the integrand
                        <literal>f(u,v)</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>params</term>
                <listitem>
                    <para>
                        a real vector <literal>[tol, iclose, maxtri, mevals, iflag]</literal>.
                        The default value is <literal>[1.d-10, 1, 50, 4000, 1]</literal>.
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>tol</term>
                            <listitem>
                                <para>the desired bound on the error. If
                                    <literal>iflag=0</literal>, <literal>tol</literal> is
                                    interpreted as a bound on the relative error; if
                                    <literal>iflag=1</literal>, the bound is on the absolute
                                    error.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>iclose</term>
                            <listitem>
                                <para>an integer parameter that determines the selection of
                                    LQM0 or LQM1 methods. If <literal>iclose=1</literal> then LQM1
                                    is used. Any other value of <literal>iclose</literal> causes
                                    LQM0 to be used. LQM0 uses function values only at interior
                                    points of the triangle. LQM1 is usually more accurate than
                                    LQM0 but involves evaluating the integrand at more points
                                    including some on the boundary of the triangle. It will
                                    usually be better to use LQM1 unless the integrand has
                                    singularities on the boundary of the triangle.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>maxtri</term>
                            <listitem>
                                <para>the maximum number of triangles in the final
                                    triangulation of the region
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>mevals</term>
                            <listitem>
                                <para>the maximum number of function evaluations to be
                                    allowed. This number will be effective in limiting the
                                    computation only if it is less than
                                    94*<literal>maxtri</literal> when LQM1 is specified or
                                    56*<literal>maxtri</literal> when LQM0 is specified.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>iflag</term>
                            <listitem>
                                <para>
                                    if <literal>iflag=0</literal>, <literal>tol</literal> is
                                    interpreted as a bound on the relative error; if <literal>iflag=1</literal>,
                                    the bound is on the absolute error.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>I</term>
                <listitem>
                    <para>the integral value</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>err</term>
                <listitem>
                    <para>the estimated error</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>int2d</literal> computes the two-dimensional integral of a
            function <literal>f</literal> over a region consisting of
            <literal>N</literal> triangles or over a single rectangle [xmin,xmax]x[ymin,ymax] (internally
            divided into two triangles). A total error estimate is obtained and
            compared with a tolerance - <literal>tol</literal> - that is provided as
            input to the subroutine. The error tolerance is treated as either relative
            or absolute depending on the input value of <literal>iflag</literal>. A
            'Local Quadrature Module' is applied to each input triangle and estimates
            of the total integral and the total error are computed. The local
            quadrature module is either subroutine LQM0 or subroutine LQM1 and the
            choice between them is determined by the value of the input variable
            <literal>iclose</literal>.
        </para>
        <para>If the total error estimate exceeds the tolerance, the triangle with
            the largest absolute error is divided into two triangles by a median to
            its longest side. The local quadrature module is then applied to each of
            the subtriangles to obtain new estimates of the integral and the error.
            This process is repeated until either (1) the error tolerance is
            satisfied, (2) the number of triangles generated exceeds the input
            parameter <literal>maxtri</literal>, (3) the number of integrand
            evaluations exceeds the input parameter <literal>mevals</literal>, or (4)
            the function senses that roundoff error is beginning to contaminate the
            result.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
deff('z=f(x,y)','z=cos(x+y)')
// computes the integral over the  triangle (0,0),(1 0),(0,1)
X = [0 1 0]';
Y = [0 0 1]';
[I,e] = int2d(X,Y,f)

// computes the integral over the square [0,1]x[0,1]
[I,e] = int2d(0,1,0,1,f)
]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="mesh2d">mesh2d</link>
            </member>
            <member>
                <link linkend="int3d">int3d</link>
            </member>
            <member>
                <link linkend="intg">intg</link>
            </member>
            <member>
                <link linkend="intl">intl</link>
            </member>
            <member>
                <link linkend="intc">intc</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
