inthp3
==============================================

Purpose
----------------

Integrates a user-defined function over the :math:`[a,+∞)` interval that is oscillatory.

Format
----------------
.. function:: y = inthp3(&f, pds, ctl, l_lim)

    :param &f: pointer to the procedure containing the function to be integrated.
    :type &f: scalar

    :param pds: pointer to instance of a :class:`DS` structure. The members of the :class:`DS` are:

        .. csv-table::
            :widths: auto

            "pds->dataMatrix", "NxK matrix."
            "pds->dataArray", "NxKxL... array."
            "pds->vnames", "string array."
            "pds->dsname", "string."
            "pds->type", "scalar."


        The contents, if any, are set by the user and are passed by :func:`inthp1` to the user-provided function without modification.

    :type pds: scalar

    :param ctl: instance of an :class:`inthpControl` structure with members

        .. list-table::
            :widths: auto

            * - ctl.maxEvaluations
              - scalar, maximum number of function evaluations, default = 1e5;
            * - ctl.p
              - scalar, termination parameter

                :0: heuristic termination, default.
                :1: deterministic termination with infinity norm.
                :2,...: deterministic termination with p-th norm.

            * - ctl.d
              - scalar termination parameter

                :1: if heuristic termination
                :0 < ctl.d < π/2: if deterministic termination

            * - ctl.eps
              - scalar, relative error bound. Default = 1e-6.

        A default *ctl* can be generated by calling :func:`inthpControlCreate`.

    :type ctl: struct

    :param l_lim: lower limits of integration.
    :type l_lim: 1xN vector

    :return y: the estimated integrals of :math:`f(x)` evaluated over the interval :math:`[a,+∞)`.

    :rtype y: Nx1 vector

Examples
----------------

::

    /*
    ** Function to be integrated
    ** note that ds pointer is
    ** first input (*pd0)
    */
    proc fct(struct DS *pd0, x);
       local m, a;

       m = pd0->dataMatrix[1];
       a = pd0->dataMatrix[2];

       retp( exp(-a*x)*cos(m*x));
    endp;

    // Define DS structure
    struct DS d0;

    // Define DS structure pointer
    struct DS *pd0;

    /*
    ** Declare instance of inthpControl
    ** structure
    */
    struct inthpControl c0;
    c0 = inthpControlCreate;

    // Set termination parameter
    c0.p = 2;

    // Set termination parameter
    c0.d = pi/3;

    // Set pointer to d0
    pd0 = &d0;

    // Set d0.dataMatrix
    m = 2;
    a = 1;
    d0.dataMatrix = m | a;

    // Set lower
    l_lim = 0;

    // Integrate function fct
    r = inthp3(&fct, pd0, c0, l_lim);

    // Print results
    format /ld 16,10;
    print r;
    print a/(a*a + m*m);

produces the following output:

::

     0.2000000000
     0.2000000000

References
++++++++++

#. "Optimal Quadratures in H_p Spaces" by K. Sikorski and F. Stenger,
   ACM Transactions on Mathematical Software, 10(2):140-151, June 1984.

Remarks
-------

This procedure is designed especially for oscillatory functions.

The user-provided function must have the following format

::

   f(struct DS *pds, x)

where

+-----+-----------------------------------------------------+
| pds | scalar, pointer to an instance of a DS structure.   |
+-----+-----------------------------------------------------+
| x   | scalar, value at which integral will be evaluated.  |
+-----+-----------------------------------------------------+

If *ctl.d* can be specified (see *Sikorski and Stenger, 1984*),
deterministic termination can be specified and accuracy guaranteed. if
not, the heuristic method can be used and the value of *ctl.d* is
disregarded.

The pointer to the instance of the data structure, *pds*, is passed
untouched to the user-provided procedure computing the function to be
integrated. Any information needed by that function can be put into that
data structure.


Source
------

inthp.src

.. seealso:: Functions :func:`inthpControlCreate`, :func:`inthp1`, :func:`inthp2`, :func:`inthp4`