inthp1
==============================================

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

Integrates a user-defined function over an infinite interval.

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

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

    :return y: estimated integral of :math:`f(x)` evaluated over the interval :math:`(-∞,+∞)`.

    :rtype y: scalar

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

::

    /*
    ** Function to be integrated
    ** note that ds pointer is
    ** first input (*pds)
    */
    proc fct(struct DS *pds, x);
        local var;
        var = pds->dataMatrix;
        retp( exp( -(x*x) / (2*var) ));
    endp;

    // Define DS structure
    struct DS d0;

    // Define DS structure pointer
    struct DS *pds;

    // Define variance
    variance = 3;

    // Set pointer to d0
    pds = &d0;

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

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

    // Integrate function fct
    r = inthp1(&fct, pds, c0);

    // Print results
    format /ld 16,10;
    print r;
    print sqrt(2*pi*variance);

results in the following output:

::

     4.3416075273
     4.3416075273

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 *clt.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:`inthp2`, :func:`inthp3`, :func:`inthp4`