<?xml version="1.0" encoding="UTF-8"?>
<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="int3d" xml:lang="en">
    <refnamediv>
        <refname>int3d</refname>
        <refpurpose>definite 3D integral by quadrature and cubature
            method
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            [result, err] = int3d(X, Y, Z, f)
            [result, err] = int3d(X, Y, Z, f, nf)
            [result, err] = int3d(X, Y, Z, f, nf, params)
            [result, err] = int3d(xmin, xmax, ymin, ymax, zmin, zmax, f)
            [result, err] = int3d(xmin, xmax, ymin, ymax, zmin, zmax, f, nf)
            [result, err] = int3d(xmin, xmax, ymin, ymax, zmin, zmax, f, nf, params)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>X</term>
                <listitem>
                    <para>
                        a 4 by <literal>N</literal> array containing the
                        abscissae of the vertices of the <literal>N</literal>
                        tetrahedrons.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Y</term>
                <listitem>
                    <para>
                        a 4 by <literal>N</literal> array containing the
                        ordinates of the vertices of the <literal>N</literal>
                        tetrahedrons.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Z</term>
                <listitem>
                    <para>
                        a 4 by <literal>N</literal> array containing the third
                        coordinates of the vertices of the <literal>N</literal>
                        tetrahedrons.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>xmin, xmax, ymin, ymax, zmin, zmax</term>
                <listitem>
                    <para>
                      real scalars defining a cuboid in the plane</para>
                </listitem>
            </varlistentry>

          <varlistentry>
                <term>f</term>
                <listitem>
                    <para>external (function or list or string) defining the integrand
                        <literal>f(xyz,nf)</literal>, where <literal>xyz</literal> is the
                        vector of a point coordinates and <literal>nf</literal> is the number of the
                      function to compute.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nf</term>
                <listitem>
                    <para>the number of functions to integrate (default is 1)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>params</term>
                <listitem>
                    <para>
                        a real vector <literal>[minpts, maxpts, epsabs, epsrel]</literal>.
                        The default value is <literal>[0, 1000, 0.0, 1.d-5]</literal>.
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>epsabs</term>
                            <listitem>
                                <para>Desired bound on the absolute error.</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>epsrel</term>
                            <listitem>
                                <para>Desired bound on the relative error.</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>minpts</term>
                            <listitem>
                                <para>Minimum number of function evaluations.</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>maxpts</term>
                            <listitem>
                                <para>Maximum number of function evaluations. The number of
                                    function evaluations over each subregion is 43
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>result</term>
                <listitem>
                    <para>the integral value or vector of the integral values.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>err</term>
                <listitem>
                    <para>estimates of absolute errors.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>The function calculates approximations of the definite integrals
          <latex alt="integral_{x_0}^{x_1(i)} f(v).dv">
           \iiint_D f_i(x,y,z) \,dx\,dy\,dz, \,i=1\dots nf
          </latex>
            where the region of integration D is a collection of <literal>N</literal>
            tetrahedrons or the single cuboid [xmin,xmax] x [ymin,ymax] x [zmin,zmax] (which is
          internally divided in 5 tetrahedrons).
        </para>
        <para>A globally adaptive strategy is applied in order to compute
            approximations <literal>result(k)</literal> hopefully satisfying, for each
            component of  <literal>I</literal>, the following claim for accuracy:
            <literal>abs(I(k)-result(k))&lt;=max(epsabs,epsrel*abs(I(k)))</literal>
        </para>
        <para>
            <literal>int3d</literal> repeatedly subdivides the tetrahedrons with
            greatest estimated errors and estimates the integrals and the errors over
            the new subtetrahedrons until the error request is met or
            <literal>maxpts</literal> function evaluations have been used.
        </para>
        <para>A 43 point integration rule with all evaluation points inside the
            tetrahedron is applied. The rule has polynomial degree 8.
        </para>
        <para>
            If the values of the input parameters <literal>epsabs</literal> or
            <literal>epsrel</literal> are selected great enough, an integration rule
            is applied over each tetrahedron and the results are added up to give the
            approximations <literal>result(k)</literal>. No further subdivision of the
            tetrahedrons will then be applied.
        </para>
        <para>
            When <literal>int3d</literal> computes estimates to a vector of
            integrals, all components of the vector are given the same treatment. That
            is, <literal>I(Fj)</literal> and <literal>I(Fk)</literal> for
            <literal>j</literal> not equal to <literal>k</literal>, are
            estimated with the same subdivision of the region of integration. For
            integrals with enough similarity, we may save time by applying
            <literal>int3d</literal> to all integrands in one call. For integrals that
            varies continuously as functions of some parameter, the estimates produced
            by <literal>int3d</literal> will also vary continuously when the same
            subdivision is applied to all components. This will generally not be the
            case when the different components are given separate treatment.
        </para>
        <para>On the other hand this feature should be used with caution when the
            different components of the integrals require clearly different
            subdivisions.
        </para>
    </refsection>
    <refsection>
        <title>References</title>
        <para>Fortran routine dcutet.f</para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// computes the intergral of exp(x*x+y*y+z*z) over the
// tetrahedron (0.,0.,0.),(1.,0.,0.),(0.,1.,0.),(0.,0.,1.)

X = [0;1;0;0];
Y = [0;0;1;0];
Z = [0;0;0;1];

// function is computed by dynamically linked Fortran code

[result, err] = int3d(X, Y, Z, 'int3dex')

// Scilab function

function v = f(xyz,numfun),v=exp(xyz'*xyz), endfunction
[result, err] = int3d(X, Y, Z, f, 1, [0,100000,1.d-5,1.d-7])

// integration over a cube  -1<=x<=1;-1<=y<=1;-1<=z<=1

function v = f(xyz,numfun), v=xyz'*xyz, endfunction
[result, err] = int3d(-1,1,-1,1,-1,1, f, 1, [0,100000,1.d-5,1.d-7])
     ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="intc">intc</link>
            </member>
            <member>
                <link linkend="intl">intl</link>
            </member>
            <member>
                <link linkend="int2d">int2d</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
