inthp2
==============================================

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

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

Format
----------------
.. function:: y = inthp2(&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 normal(struct DS *pd0, x);
       local var;

       var = pd0->dataMatrix;

       retp( (1/sqrt(2*pi*var))*exp( -(x*x) / (2*var) ));
    endp;

    // Define DS structure
    struct DS d0;

    // Define DS structure pointer
    struct DS *pd0;

    // Set pointer to d0
    pd0 = &d0;

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

    // Lower limit
    l_lim = 2;

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

    // Set termination parameter
    c0.p = 2;

    // Set var
    var = 1;

    // Set d0 data matrix
    d0.dataMatrix = var;

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

    // Print results
    format /ld 16,10;
    print r;
    print cdfnc(2);

produces the following output:

::

     0.0227501281
     0.0227501319

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
-------

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:`inthp3`, :func:`inthp4`