# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.3 `quad` Chapter.
``quad`` - Quadrature
This module provides functions for the numerical evaluation of definite integrals in one or more dimensions and for evaluating weights and abscissae of integration rules.
See Also
--------
``naginterfaces.library.examples.quad`` :
This subpackage contains examples for the ``quad`` module.
See also the :ref:`library_quad_ex` subsection.
Functionality Index
-------------------
**Korobov optimal coefficients for use in** :meth:`md_numth` **and** :meth:`md_numth_vec`
when number of points is a product of :math:`2` primes: :meth:`md_numth_coeff_2prime`
when number of points is prime: :meth:`md_numth_coeff_prime`
**Multidimensional quadrature**
over a finite two-dimensional region: :meth:`dim2_fin`
over a general product region
Korobov--Conroy number-theoretic method: :meth:`md_numth`
Sag--Szekeres method (also over :math:`n`-sphere): :meth:`md_sphere`
variant of :meth:`md_numth` especially efficient on vector machines: :meth:`md_numth_vec`
over a hyper-rectangle
adaptive method
: :meth:`md_adapt`
multiple integrands: :meth:`md_adapt_multi`
Gaussian quadrature rule-evaluation: :meth:`md_gauss`
Monte Carlo method: :meth:`md_mcarlo`
sparse grid method (with user transformation)
muliple integrands, vectorized interface: :meth:`md_sgq_multi_vec`
over an :math:`n`-simplex: :meth:`md_simplex`
over an :math:`n`-sphere :math:`\left(n\leq 4\right)`
allowing for badly behaved integrands: :meth:`md_sphere_bad`
**One-dimensional quadrature**
adaptive integration of a function over a finite interval
strategy due to Gonnet
suitable for badly behaved integrals
vectorized interface: :meth:`dim1_fin_gonnet_vec`
strategy due to Patterson
suitable for well-behaved integrands, except possibly at end-points: :meth:`dim1_fin_well`
strategy due to Piessens and de Doncker
allowing for singularities at user-specified break-points: :meth:`dim1_fin_brkpts`
suitable for badly behaved integrands: :meth:`dim1_fin_general`
suitable for highly oscillatory integrals: :meth:`dim1_fin_osc_fn`
weight function :math:`\cos\left(\omega x\right)` or :math:`\sin\left(\omega x\right)`: :meth:`dim1_fin_wtrig`
weight function :math:`1/\left(x-c\right)` Cauchy principal value (Hilbert transform): :meth:`dim1_fin_wcauchy`
weight function with end-point singularities of algebraico-logarithmic type: :meth:`dim1_fin_wsing`
adaptive integration of a function over a infinite or semi-infinite interval
strategy due to Piessens and de Doncker: :meth:`dim1_inf_general`
adaptive integration of a function over an infinite interval or semi-infinite interval
weight function :math:`\cos\left(\omega x\right)` or :math:`\sin\left(\omega x\right)`: :meth:`dim1_inf_wtrig`
integration of a function defined by data values only
Gill--Miller method: :meth:`dim1_data`
non-adaptive integration over a finite, semi-infinite or infinite interval
using pre-computed weights and abscissae
specific integral with weight :math:`\mathrm{exp}\left({-x}^2\right)` over semi-infinite interval: :meth:`dim1_inf_exp_wt`
vectorized interface: :meth:`dim1_gauss_vec`
non-adaptive integration over a finite interval
: :meth:`dim1_fin_smooth`
with provision for indefinite integrals also: :meth:`dim1_indef`
reverse communication
adaptive integration over a finite interval
multiple integrands
efficient on vector machines: :meth:`dim1_gen_vec_multi_rcomm`
**Service functions**
array size query for :meth:`dim1_gen_vec_multi_rcomm`: :meth:`dim1_gen_vec_multi_dimreq`
general option getting: :meth:`opt_get`
general option setting and initialization: :meth:`opt_set`
**Weights and abscissae for Gaussian quadrature rules**
method of Golub and Welsch
calculating the weights and abscissae: :meth:`dim1_gauss_wrec`
generate recursive coefficients: :meth:`dim1_gauss_recm`
more general choice of rule
calculating the weights and abscissae: :meth:`dim1_gauss_wgen`
restricted choice of rule
using pre-computed weights and abscissae: :meth:`dim1_gauss_wres`
For full information please refer to the NAG Library document
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01intro.html
"""
# NAG Copyright 2017-2024.
[docs]def dim1_fin_well(a, b, epsr, f, nlimit, data=None):
r"""
``dim1_fin_well`` computes a definite integral over a finite range to a specified relative accuracy using a method described by Patterson.
.. _d01ah-py2-py-doc:
For full information please refer to the NAG Library document for d01ah
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01ahf.html
.. _d01ah-py2-py-parameters:
**Parameters**
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
**epsr** : float
The relative accuracy required.
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a given point.
**Parameters**
**x** : float
The point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of the integrand at :math:`\mathrm{x}`.
**nlimit** : int
A limit to the number of function evaluations. If :math:`\mathrm{nlimit}\leq 0`, the function uses a default limit of :math:`10000`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**din** : float
The value of the definite interval.
**npts** : int
The number of function evaluations used in the calculation of the integral.
**relerr** : float
A rough estimate of the relative error achieved.
.. _d01ah-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`3`)
On entry, :math:`\mathrm{epsr} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{epsr} > 0.0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
Integral has failed to converge to requested accuracy.
(`errno` :math:`2`)
Too many unsuccessful levels of subdivision.
.. _d01ah-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``dim1_fin_well`` computes a definite integral of the form
.. math::
\int_a^bf\left(x\right){dx}\text{.}
The method uses as its basis a family of interlacing high precision rules (see Patterson (1968)) using :math:`1`, :math:`3`, :math:`7`, :math:`15`, :math:`31`, :math:`63`, :math:`127` and :math:`255` nodes.
Initially the family is applied in sequence to the integrand.
When two successive rules differ relatively by less than the required relative accuracy, the last rule used is taken as the value of the integral and the operation is regarded as successful.
If all rules in the family have been applied unsuccessfully, subdivision is invoked.
The subdivision strategy is as follows.
The interval under scrutiny is divided into two sub-intervals (not always equal).
The basic family is then applied to the first sub-interval.
If the required accuracy is not obtained, the interval is stored for future examination (see :math:`\mathrm{errno}` = 2) and the second sub-interval is examined.
Should the basic family again be unsuccessful, then the sub-interval is further subdivided and the whole process repeated.
Successful integrations are accumulated as the partial value of the integral.
When all possible successful integrations have been completed, those previously unsuccessful sub-intervals placed in store are examined.
A large number of refinements are incorporated to improve the performance.
Some of these are:
(a) The rate of convergence of the basic family is monitored and used to make a decision to abort and subdivide before the full sequence has been applied.
(#) The :math:`\epsilon`-algorithm is applied to the basic results in an attempt to increase the convergence rate. See Wynn (1956).
(#) An attempt is made to detect sharp end point peaks and singularities in each sub-interval and to apply appropriate transformations to smooth the integrand. This consideration is also used to select interval sizes in the subdivision process.
(#) The relative accuracy sought in each sub-interval is adjusted in accordance with its likely contribution to the total integral.
(#) Random transformations of the integrand are applied to improve reliability in some instances.
.. _d01ah-py2-py-references:
**References**
Patterson, T N L, 1968, `The Optimum addition of points to quadrature formulae`, Math. Comput. (22), 847--856
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_fin_bad(f, a, b, epsabs, epsrel, lw=800, liw=None, data=None):
r"""
``dim1_fin_bad`` is a general purpose integrator which calculates an approximation to the integral of a function :math:`f\left(x\right)` over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{.}
.. deprecated:: 27.1.0.0
``dim1_fin_bad`` will be removed in naginterfaces 31.3.0.0.
Please use :meth:`dim1_fin_general` instead.
See also the :ref:`Replacement Calls <replace>` document.
.. _d01aj-py2-py-doc:
For full information please refer to the NAG Library document for d01aj
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01ajf.html
.. _d01aj-py2-py-parameters:
**Parameters**
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a given point.
**Parameters**
**x** : float
The point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of the integrand at :math:`\mathrm{x}`.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01ajf.html#accuracy>`__.
**epsrel** : float
The relative accuracy required. If :math:`\mathrm{epsrel}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01ajf.html#accuracy>`__.
**lw** : int, optional
The value of :math:`\mathrm{lw}` (together with that of :math:`\mathrm{liw}`) imposes a bound on the number of sub-intervals into which the interval of integration may be divided by the function. The number of sub-intervals cannot exceed :math:`\mathrm{lw}/4`. The more difficult the integrand, the larger :math:`\mathrm{lw}` should be.
**liw** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`\mathrm{lw}/4`.
The number of sub-intervals into which the interval of integration may be divided cannot exceed :math:`\mathrm{liw}`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**w** : float, ndarray, shape :math:`\left(\mathrm{lw}\right)`
Details of the computation see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01ajf.html#fcomments>`__ for more information.
**iw** : int, ndarray, shape :math:`\left(\mathrm{liw}\right)`
:math:`\mathrm{iw}[0]` contains the actual number of sub-intervals used. The rest of the array is used as workspace.
.. _d01aj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`6`)
On entry, :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{liw}\geq 1`.
(`errno` :math:`6`)
On entry, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{lw}\geq 4`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{LIMIT}`) has been reached: :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
(`errno` :math:`4`)
Round-off error is detected in the extrapolation table.
(`errno` :math:`5`)
The integral is probably divergent or slowly convergent.
.. _d01aj-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``dim1_fin_bad`` is based on the QUADPACK routine QAGS (see Piessens `et al.` (1983)).
It is an adaptive function, using the Gauss :math:`10`-point and Kronrod :math:`21`-point rules.
The algorithm, described in de Doncker (1978), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the :math:`\epsilon`-algorithm (see Wynn (1956)) to perform extrapolation.
The local error estimation is described in Piessens `et al.` (1983).
The function is suitable as a general purpose integrator, and can be used when the integrand has singularities, especially when these are of algebraic or logarithmic type.
``dim1_fin_bad`` requires you to supply a function to evaluate the integrand at a single point.
The function :meth:`dim1_fin_bad_vec` uses an identical algorithm but requires you to supply a function to evaluate the integrand at an array of points.
Therefore, :meth:`dim1_fin_bad_vec` may be more efficient for some problem types and some machine architectures.
.. _d01aj-py2-py-references:
**References**
de Doncker, E, 1978, `An adaptive extrapolation algorithm for automatic integration`, ACM SIGNUM Newsl. (13(2)), 12--18
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_fin_osc(f, a, b, epsabs, epsrel, lw=800, liw=None, data=None):
r"""
``dim1_fin_osc`` is an adaptive integrator, especially suited to oscillating, nonsingular integrands, which calculates an approximation to the integral of a function :math:`f\left(x\right)` over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{.}
.. deprecated:: 27.1.0.0
``dim1_fin_osc`` will be removed in naginterfaces 31.3.0.0.
Please use :meth:`dim1_fin_osc_fn` instead.
See also the :ref:`Replacement Calls <replace>` document.
.. _d01ak-py2-py-doc:
For full information please refer to the NAG Library document for d01ak
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01akf.html
.. _d01ak-py2-py-parameters:
**Parameters**
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a given point.
**Parameters**
**x** : float
The point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of the integrand at :math:`\mathrm{x}`.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01akf.html#accuracy>`__.
**epsrel** : float
The relative accuracy required. If :math:`\mathrm{epsrel}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01akf.html#accuracy>`__.
**lw** : int, optional
The value of :math:`\mathrm{lw}` (together with that of :math:`\mathrm{liw}`) imposes a bound on the number of sub-intervals into which the interval of integration may be divided by the function. The number of sub-intervals cannot exceed :math:`\mathrm{lw}/4`. The more difficult the integrand, the larger :math:`\mathrm{lw}` should be.
**liw** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`\mathrm{lw}/4`.
The number of sub-intervals into which the interval of integration may be divided cannot exceed :math:`\mathrm{liw}`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**w** : float, ndarray, shape :math:`\left(\mathrm{lw}\right)`
Details of the computation see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01akf.html#fcomments>`__ for more information.
**iw** : int, ndarray, shape :math:`\left(\mathrm{liw}\right)`
:math:`\mathrm{iw}[0]` contains the actual number of sub-intervals used. The rest of the array is used as workspace.
.. _d01ak-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`4`)
On entry, :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{liw}\geq 1`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{lw}\geq 4`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{LIMIT}`) has been reached: :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
.. _d01ak-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``dim1_fin_osc`` is based on the QUADPACK routine QAG (see Piessens `et al.` (1983)).
It is an adaptive function, using the Gauss :math:`30`-point and Kronrod :math:`61`-point rules.
A 'global' acceptance criterion (as defined by Malcolm and Simpson (1976)) is used.
The local error estimation is described in Piessens `et al.` (1983).
Because ``dim1_fin_osc`` is based on integration rules of high order, it is especially suitable for nonsingular oscillating integrands.
``dim1_fin_osc`` requires you to supply a function to evaluate the integrand at a single point.
The function :meth:`dim1_fin_osc_vec` uses an identical algorithm but requires you to supply a function to evaluate the integrand at an array of points.
Therefore, :meth:`dim1_fin_osc_vec` will be more efficient if the evaluation can be performed in vector mode on a vector-processing machine.
.. _d01ak-py2-py-references:
**References**
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, 1973, `An algorithm for automatic integration`, Angew. Inf. (15), 399--401
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
"""
raise NotImplementedError
[docs]def dim1_fin_sing(f, a, b, points, epsabs, epsrel, lw=800, liw=None, data=None):
r"""
``dim1_fin_sing`` is a general purpose integrator which calculates an approximation to the integral of a function :math:`f\left(x\right)` over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}
where the integrand may have local singular behaviour at a finite number of points within the integration interval.
.. deprecated:: 27.1.0.0
``dim1_fin_sing`` will be removed in naginterfaces 31.3.0.0.
Please use :meth:`dim1_fin_brkpts` instead.
See also the :ref:`Replacement Calls <replace>` document.
.. _d01al-py2-py-doc:
For full information please refer to the NAG Library document for d01al
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01alf.html
.. _d01al-py2-py-parameters:
**Parameters**
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a given point.
**Parameters**
**x** : float
The point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of the integrand at :math:`\mathrm{x}`.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
**points** : float, array-like, shape :math:`\left(\textit{npts}\right)`
The user-specified break-points.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01alf.html#accuracy>`__.
**epsrel** : float
The relative accuracy required. If :math:`\mathrm{epsrel}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01alf.html#accuracy>`__.
**lw** : int, optional
The value of :math:`\mathrm{lw}` (together with that of :math:`\mathrm{liw}`) imposes a bound on the number of sub-intervals into which the interval of integration may be divided by the function. The number of sub-intervals cannot exceed :math:`\left(\mathrm{lw}-2\times \textit{npts}-4\right)/4`. The more difficult the integrand, the larger :math:`\mathrm{lw}` should be.
**liw** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`\mathrm{lw}/2`.
The number of sub-intervals into which the interval of integration may be divided cannot exceed :math:`\left(\mathrm{liw}-\textit{npts}-2\right)/2`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**w** : float, ndarray, shape :math:`\left(\mathrm{lw}\right)`
Details of the computation see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01alf.html#fcomments>`__ for more information.
**iw** : int, ndarray, shape :math:`\left(\mathrm{liw}\right)`
:math:`\mathrm{iw}[0]` contains the actual number of sub-intervals used. The rest of the array is used as workspace.
.. _d01al-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`6`)
On entry, :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{LIMIT} > \textit{npts}`.
(`errno` :math:`6`)
On entry, break-points are specified outside :math:`\left(\mathrm{a}, \mathrm{b}\right)`: :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`6`)
On entry, :math:`\textit{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{npts}\geq 0`.
(`errno` :math:`7`)
On entry, :math:`\mathrm{liw}` is too small. :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`. Minimum possible dimension: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`7`)
On entry, :math:`\mathrm{lw}` is too small. :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle`. Minimum possible dimension: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{LIMIT}`) has been reached: :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle` :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle` :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle` :math:`\textit{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
(`errno` :math:`4`)
Round-off error is detected in the extrapolation table.
(`errno` :math:`5`)
The integral is probably divergent or slowly convergent.
.. _d01al-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``dim1_fin_sing`` is based on the QUADPACK routine QAGP (see Piessens `et al.` (1983)).
It is very similar to :meth:`dim1_fin_bad`, but allows you to supply 'break-points', points at which the integrand is known to be difficult.
It employs an adaptive algorithm, using the Gauss :math:`10`-point and Kronrod :math:`21`-point rules.
The algorithm, described in de Doncker (1978), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the :math:`\epsilon`-algorithm (see Wynn (1956)) to perform extrapolation.
The user-supplied 'break-points' always occur as the end points of some sub-interval during the adaptive process.
The local error estimation is described in Piessens `et al.` (1983).
.. _d01al-py2-py-references:
**References**
de Doncker, E, 1978, `An adaptive extrapolation algorithm for automatic integration`, ACM SIGNUM Newsl. (13(2)), 12--18
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_inf(f, bound, inf, epsabs, epsrel, lw=800, liw=None, data=None):
r"""
``dim1_inf`` calculates an approximation to the integral of a function :math:`f\left(x\right)` over an infinite or semi-infinite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{.}
.. deprecated:: 27.1.0.0
``dim1_inf`` will be removed in naginterfaces 31.3.0.0.
Please use :meth:`dim1_inf_general` instead.
See also the :ref:`Replacement Calls <replace>` document.
.. _d01am-py2-py-doc:
For full information please refer to the NAG Library document for d01am
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01amf.html
.. _d01am-py2-py-parameters:
**Parameters**
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a given point.
**Parameters**
**x** : float
The point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of the integrand at :math:`\mathrm{x}`.
**bound** : float
The finite limit of the integration range (if present). :math:`\mathrm{bound}` is not used if the interval is doubly infinite.
**inf** : int
Indicates the kind of integration range.
:math:`\mathrm{inf} = 1`
The range is :math:`\left[\mathrm{bound}, {{+\infty }}\right)`.
:math:`\mathrm{inf} = -1`
The range is :math:`\left({{-\infty }}, \mathrm{bound}\right]`.
:math:`\mathrm{inf} = 2`
The range is :math:`\left({{-\infty }}, {{+\infty }}\right)`.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01amf.html#accuracy>`__.
**epsrel** : float
The relative accuracy required. If :math:`\mathrm{epsrel}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01amf.html#accuracy>`__.
**lw** : int, optional
The value of :math:`\mathrm{lw}` (together with that of :math:`\mathrm{liw}`) imposes a bound on the number of sub-intervals into which the interval of integration may be divided by the function. The number of sub-intervals cannot exceed :math:`\mathrm{lw}/4`. The more difficult the integrand, the larger :math:`\mathrm{lw}` should be.
**liw** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`\mathrm{lw}/4`.
The number of sub-intervals into which the interval of integration may be divided cannot exceed :math:`\mathrm{liw}`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**w** : float, ndarray, shape :math:`\left(\mathrm{lw}\right)`
Details of the computation see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01amf.html#fcomments>`__ for more information.
**iw** : int, ndarray, shape :math:`\left(\mathrm{liw}\right)`
:math:`\mathrm{iw}[0]` contains the actual number of sub-intervals used. The rest of the array is used as workspace.
.. _d01am-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`6`)
On entry, :math:`\mathrm{inf} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{inf} = -1`, :math:`1` or :math:`2`.
(`errno` :math:`6`)
On entry, :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{liw}\geq 1`.
(`errno` :math:`6`)
On entry, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{lw}\geq 4`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{LIMIT}`) has been reached: :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around one of the sub-intervals :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)` or :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
(`errno` :math:`4`)
Round-off error is detected in the extrapolation table.
(`errno` :math:`5`)
The integral is probably divergent or slowly convergent.
.. _d01am-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``dim1_inf`` is based on the QUADPACK routine QAGI (see Piessens `et al.` (1983)).
The entire infinite integration range is first transformed to :math:`\left[0, 1\right]` using one of the identities:
.. math::
\int_{{-\infty }}^af\left(x\right){dx} = \int_0^1f\left(a-\frac{{1-t}}{t}\right)\frac{1}{t^2}{dt}
.. math::
\int_a^{\infty }f\left(x\right){dx} = \int_0^1f\left(a+\frac{{1-t}}{t}\right)\frac{1}{t^2}{dt}
.. math::
\int_{{-\infty }}^{\infty }f\left(x\right){dx} = \int_0^{\infty }\left(f\left(x\right)+f\left(-x\right)\right){dx} = \int_0^1\text{ }\left[f\left(\frac{{1-t}}{t}\right)+f\left(\frac{{-1+t}}{t}\right)\right]\frac{1}{t^2}{dt}
where :math:`a` represents a finite integration limit.
An adaptive procedure, based on the Gauss :math:`7`-point and Kronrod :math:`15`-point rules, is then employed on the transformed integral.
The algorithm, described in de Doncker (1978), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the :math:`\epsilon`-algorithm (see Wynn (1956)) to perform extrapolation.
The local error estimation is described in Piessens `et al.` (1983).
.. _d01am-py2-py-references:
**References**
de Doncker, E, 1978, `An adaptive extrapolation algorithm for automatic integration`, ACM SIGNUM Newsl. (13(2)), 12--18
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_fin_wtrig(g, a, b, omega, key, epsabs, epsrel, lw=800, liw=None, data=None):
r"""
``dim1_fin_wtrig`` calculates an approximation to the sine or the cosine transform of a function :math:`g` over :math:`\left[a, b\right]`:
.. math::
I = \int_a^bg\left(x\right)\sin\left(\omega x\right){dx}\quad \text{ or }\quad I = \int_a^bg\left(x\right)\cos\left(\omega x\right){dx}
(for a user-specified value of :math:`\omega`).
.. _d01an-py2-py-doc:
For full information please refer to the NAG Library document for d01an
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01anf.html
.. _d01an-py2-py-parameters:
**Parameters**
**g** : callable retval = g(x, data=None)
:math:`\mathrm{g}` must return the value of the function :math:`g` at a given point :math:`\mathrm{x}`.
**Parameters**
**x** : float
The point at which the function :math:`g` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`g\left(x\right)` evaluated at :math:`\mathrm{x}`.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
**omega** : float
The argument :math:`\omega` in the weight function of the transform.
**key** : int
Indicates which integral is to be computed.
:math:`\mathrm{key} = 1`
:math:`w\left(x\right) = \cos\left(\omega x\right)`.
:math:`\mathrm{key} = 2`
:math:`w\left(x\right) = \sin\left(\omega x\right)`.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01anf.html#accuracy>`__.
**epsrel** : float
The relative accuracy required. If :math:`\mathrm{epsrel}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01anf.html#accuracy>`__.
**lw** : int, optional
The value of :math:`\mathrm{lw}` (together with that of :math:`\mathrm{liw}`) imposes a bound on the number of sub-intervals into which the interval of integration may be divided by the function. The number of sub-intervals cannot exceed :math:`\mathrm{lw}/4`. The more difficult the integrand, the larger :math:`\mathrm{lw}` should be.
**liw** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`\mathrm{lw}/2`.
The number of sub-intervals into which the interval of integration may be divided cannot exceed :math:`\mathrm{liw}/2`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**w** : float, ndarray, shape :math:`\left(\mathrm{lw}\right)`
Details of the computation see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01anf.html#fcomments>`__ for more information.
**iw** : int, ndarray, shape :math:`\left(\mathrm{liw}\right)`
:math:`\mathrm{iw}[0]` contains the actual number of sub-intervals used. The rest of the array is used as workspace.
.. _d01an-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`6`)
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{key}\geq 1` and :math:`\mathrm{key}\leq 2`.
(`errno` :math:`7`)
On entry, :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{liw}\geq 2`.
(`errno` :math:`7`)
On entry, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{lw}\geq 4`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{LIMIT}`) has been reached: :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
(`errno` :math:`4`)
Round-off error is detected in the extrapolation table.
(`errno` :math:`5`)
The integral is probably divergent or slowly convergent.
.. _d01an-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``dim1_fin_wtrig`` is based on the QUADPACK routine QFOUR (see Piessens `et al.` (1983)).
It is an adaptive function, designed to integrate a function of the form :math:`g\left(x\right)w\left(x\right)`, where :math:`w\left(x\right)` is either :math:`\sin\left(\omega x\right)` or :math:`\cos\left(\omega x\right)`.
If a sub-interval has length
.. math::
L = \left\lvert b-a\right\rvert 2^{{-l}}
then the integration over this sub-interval is performed by means of a modified Clenshaw--Curtis procedure (see Piessens and Branders (1975)) if :math:`L\omega > 4` and :math:`l\leq 20\text{.}` In this case a Chebyshev series approximation of degree :math:`24` is used to approximate :math:`g\left(x\right)`, while an error estimate is computed from this approximation together with that obtained using Chebyshev series of degree :math:`12`.
If the above conditions do not hold then Gauss :math:`7`-point and Kronrod :math:`15`-point rules are used.
The algorithm, described in Piessens `et al.` (1983), incorporates a global acceptance criterion (as defined in Malcolm and Simpson (1976)) together with the :math:`\epsilon`-algorithm (see Wynn (1956)) to perform extrapolation.
The local error estimation is described in Piessens `et al.` (1983).
.. _d01an-py2-py-references:
**References**
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R and Branders, M, 1975, `Algorithm 002: computation of oscillating integrals`, J. Comput. Appl. Math. (1), 153--164
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_fin_wsing(g, a, b, alfa, beta, key, epsabs, epsrel, lw=800, liw=None, data=None):
r"""
``dim1_fin_wsing`` is an adaptive integrator which calculates an approximation to the integral of a function :math:`g\left(x\right)w\left(x\right)` over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bg\left(x\right)w\left(x\right){dx}
where the weight function :math:`w` has end point singularities of algebraico-logarithmic type.
.. _d01ap-py2-py-doc:
For full information please refer to the NAG Library document for d01ap
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01apf.html
.. _d01ap-py2-py-parameters:
**Parameters**
**g** : callable retval = g(x, data=None)
:math:`\mathrm{g}` must return the value of the function :math:`g` at a given point :math:`\mathrm{x}`.
**Parameters**
**x** : float
The point at which the function :math:`g` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`g\left(x\right)` evaluated at :math:`\mathrm{x}`.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration.
**alfa** : float
The argument :math:`\alpha` in the weight function.
**beta** : float
The argument :math:`\beta` in the weight function.
**key** : int
Indicates which weight function is to be used.
:math:`\mathrm{key} = 1`
:math:`w\left(x\right) = \left(x-a\right)^{\alpha }\left(b-x\right)^{\beta }`.
:math:`\mathrm{key} = 2`
:math:`w\left(x\right) = \left(x-a\right)^{\alpha }\left(b-x\right)^{\beta }\mathrm{ln}\left(x-a\right)`.
:math:`\mathrm{key} = 3`
:math:`w\left(x\right) = \left(x-a\right)^{\alpha }\left(b-x\right)^{\beta }\mathrm{ln}\left(b-x\right)`.
:math:`\mathrm{key} = 4`
:math:`w\left(x\right) = \left(x-a\right)^{\alpha }\left(b-x\right)^{\beta }\mathrm{ln}\left(x-a\right)\mathrm{ln}\left(b-x\right)`.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01apf.html#accuracy>`__.
**epsrel** : float
The relative accuracy required. If :math:`\mathrm{epsrel}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01apf.html#accuracy>`__.
**lw** : int, optional
The value of :math:`\mathrm{lw}` (together with that of :math:`\mathrm{liw}`) imposes a bound on the number of sub-intervals into which the interval of integration may be divided by the function. The number of sub-intervals cannot exceed :math:`\mathrm{lw}/4`. The more difficult the integrand, the larger :math:`\mathrm{lw}` should be.
**liw** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`\mathrm{lw}/4`.
The number of sub-intervals into which the interval of integration may be divided cannot exceed :math:`\mathrm{liw}`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**w** : float, ndarray, shape :math:`\left(\mathrm{lw}\right)`
Details of the computation see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01apf.html#fcomments>`__ for more information.
**iw** : int, ndarray, shape :math:`\left(\mathrm{liw}\right)`
:math:`\mathrm{iw}[0]` contains the actual number of sub-intervals used. The rest of the array is used as workspace.
.. _d01ap-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`4`)
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{key}\leq 4`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{key}\geq 1`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{beta} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{beta} > {-1.0}`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{alfa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{alfa} > {-1.0}`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{b} > \mathrm{a}`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{liw}\geq 2`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{lw}\geq 8`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{LIMIT}`) has been reached: :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
.. _d01ap-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``dim1_fin_wsing`` is based on the QUADPACK routine QAWSE (see Piessens `et al.` (1983)) and integrates a function of the form :math:`g\left(x\right)w\left(x\right)`, where the weight function :math:`w\left(x\right)` may have algebraico-logarithmic singularities at the end points :math:`a` and/or :math:`b`.
The strategy is a modification of that in :meth:`dim1_fin_osc_fn`.
We start by bisecting the original interval and applying modified Clenshaw--Curtis integration of orders :math:`12` and :math:`24` to both halves.
Clenshaw--Curtis integration is then used on all sub-intervals which have :math:`a` or :math:`b` as one of their end points (see Piessens `et al.` (1974)).
On the other sub-intervals Gauss--Kronrod (:math:`7`--:math:`15` point) integration is carried out.
A 'global' acceptance criterion (as defined by Malcolm and Simpson (1976)) is used.
The local error estimation control is described in Piessens `et al.` (1983).
.. _d01ap-py2-py-references:
**References**
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Piessens, R, Mertens, I and Branders, M, 1974, `Integration of functions having end-point singularities`, Angew. Inf. (16), 65--68
"""
raise NotImplementedError
[docs]def dim1_fin_wcauchy(g, a, b, c, epsabs, epsrel, lw=800, liw=None, data=None):
r"""
``dim1_fin_wcauchy`` calculates an approximation to the Hilbert transform of a function :math:`g\left(x\right)` over :math:`\left[a, b\right]`:
.. math::
I = \int_a^b\frac{{g\left(x\right)}}{{x-c}}{dx}
for user-specified values of :math:`a`, :math:`b` and :math:`c`.
.. _d01aq-py2-py-doc:
For full information please refer to the NAG Library document for d01aq
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01aqf.html
.. _d01aq-py2-py-parameters:
**Parameters**
**g** : callable retval = g(x, data=None)
:math:`\mathrm{g}` must return the value of the function :math:`g` at a given point :math:`\mathrm{x}`.
**Parameters**
**x** : float
The point at which the function :math:`g` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`g\left(x\right)` evaluated at :math:`\mathrm{x}`.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
**c** : float
The argument :math:`c` in the weight function.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01aqf.html#accuracy>`__.
**epsrel** : float
The relative accuracy required. If :math:`\mathrm{epsrel}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01aqf.html#accuracy>`__.
**lw** : int, optional
The value of :math:`\mathrm{lw}` (together with that of :math:`\mathrm{liw}`) imposes a bound on the number of sub-intervals into which the interval of integration may be divided by the function. The number of sub-intervals cannot exceed :math:`\mathrm{lw}/4`. The more difficult the integrand, the larger :math:`\mathrm{lw}` should be.
**liw** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`\mathrm{lw}/4`.
The number of sub-intervals into which the interval of integration may be divided cannot exceed :math:`\mathrm{liw}`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**w** : float, ndarray, shape :math:`\left(\mathrm{lw}\right)`
Details of the computation see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01aqf.html#fcomments>`__ for more information.
**iw** : int, ndarray, shape :math:`\left(\mathrm{liw}\right)`
:math:`\mathrm{iw}[0]` contains the actual number of sub-intervals used. The rest of the array is used as workspace.
.. _d01aq-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`4`)
On entry, :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{c} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{c}\neq \mathrm{a}` and :math:`\mathrm{c}\neq \mathrm{b}`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{liw}\geq 1`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{lw}\geq 4`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{LIMIT}`) has been reached: :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
.. _d01aq-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``dim1_fin_wcauchy`` is based on the QUADPACK routine QAWC (see Piessens `et al.` (1983)) and integrates a function of the form :math:`g\left(x\right)w\left(x\right)`, where the weight function
.. math::
w\left(x\right) = \frac{1}{{x-c}}
is that of the Hilbert transform. (If :math:`a < c < b` the integral has to be interpreted in the sense of a Cauchy principal value.) It is an adaptive function which employs a 'global' acceptance criterion (as defined by Malcolm and Simpson (1976)).
Special care is taken to ensure that :math:`c` is never the end point of a sub-interval (see Piessens `et al.` (1976)).
On each sub-interval :math:`\left(c_1, c_2\right)` modified Clenshaw--Curtis integration of orders :math:`12` and :math:`24` is performed if :math:`c_1-d\leq c\leq c_2+d` where :math:`d = \left(c_2-c_1\right)/20`.
Otherwise the Gauss :math:`7`-point and Kronrod :math:`15`-point rules are used.
The local error estimation is described by Piessens `et al.` (1983).
.. _d01aq-py2-py-references:
**References**
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Piessens, R, van Roy--Branders, M and Mertens, I, 1976, `The automatic evaluation of Cauchy principal value integrals`, Angew. Inf. (18), 31--35
"""
raise NotImplementedError
[docs]def dim1_indef(a, b, f, relacc, absacc, maxrul, iparm, alpha, data=None):
r"""
``dim1_indef`` computes definite and indefinite integrals over a finite range to a specified relative or absolute accuracy, using the method described in Patterson (1968).
.. _d01ar-py2-py-doc:
For full information please refer to the NAG Library document for d01ar
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01arf.html
.. _d01ar-py2-py-parameters:
**Parameters**
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand at a given point.
**Parameters**
**x** : float
The point in :math:`\left[a, b\right]` at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`f\left(x\right)` evaluated at :math:`\mathrm{x}`.
**relacc** : float
The relative accuracy required. If convergence according to absolute accuracy is required, :math:`\mathrm{relacc}` should be set to zero (but see also `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01arf.html#accuracy>`__). If :math:`\mathrm{relacc} < 0.0`, its absolute value is used.
If :math:`\mathrm{iparm} = 2`, :math:`\mathrm{relacc}` is not used.
**absacc** : float
The absolute accuracy required. If convergence according to relative accuracy is required, :math:`\mathrm{absacc}` should be set to zero (but see also `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01arf.html#accuracy>`__). If :math:`\mathrm{absacc} < 0.0`, its absolute value is used.
If :math:`\mathrm{iparm} = 2`, :math:`\mathrm{absacc}` is not used.
**maxrul** : int
The maximum number of successive rules that may be used.
**iparm** : int
Indicates the task to be performed by the function.
:math:`\mathrm{iparm} = 0`
Only the definite integral over :math:`\left[a, b\right]` is evaluated.
:math:`\mathrm{iparm} = 1`
As well as the definite integral, the expansion of the integrand in Legendre polynomials over :math:`\left[a, b\right]` is calculated, using the same values of the integrand as used to compute the integral. The expansion coefficients, and some other quantities, are returned in :math:`\mathrm{alpha}` for later use in computing indefinite integrals.
:math:`\mathrm{iparm} = 2`
:math:`f\left(t\right)` is integrated analytically over :math:`\left[a, b\right]` using the previously computed expansion, stored in :math:`\mathrm{alpha}`. No further evaluations of the integrand are required. The function must previously have been called with :math:`\mathrm{iparm} = 1` and the interval :math:`\left[a, b\right]` must lie within that specified for the previous call. In this case only the arguments :math:`\mathrm{a}`, :math:`\mathrm{b}`, :math:`\mathrm{iparm}`, :math:`\mathrm{ans}` and :math:`\mathrm{alpha}` are used.
**alpha** : float, array-like, shape :math:`\left(390\right)`
If :math:`\mathrm{iparm} = 2`, :math:`\mathrm{alpha}` must contain the coefficients of the Legendre expansions of the integrand, as returned by a previous call of ``dim1_indef`` with :math:`\mathrm{iparm} = 1` and a range containing the present range.
If :math:`\mathrm{iparm} = 0` or :math:`1`, :math:`\mathrm{alpha}` need not be set on entry.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**acc** : float
If :math:`\mathrm{iparm} = 0` or :math:`1`, :math:`\mathrm{acc}` contains the absolute value of the difference between the last two successive estimates of the integral. This may be used as a measure of the accuracy actually achieved.
If :math:`\mathrm{iparm} = 2`, :math:`\mathrm{acc}` is not used.
**ans** : float
The estimated value of the integral.
**n** : int
When :math:`\mathrm{iparm} = 0` or :math:`1`, :math:`\mathrm{n}` contains the number of integrand evaluations used in the calculation of the integral.
If :math:`\mathrm{iparm} = 2`, :math:`\mathrm{n}` is not used.
**alpha** : float, ndarray, shape :math:`\left(390\right)`
If :math:`\mathrm{iparm} = 1`, the first :math:`m` elements of :math:`\mathrm{alpha}` hold the coefficients of the Legendre expansion of the integrand, and the value of :math:`m` is stored in :math:`\mathrm{alpha}[389]`. :math:`\mathrm{alpha}` must not be changed between a call with :math:`\mathrm{iparm} = 1` and subsequent calls with :math:`\mathrm{iparm} = 2`.
If :math:`\mathrm{iparm} = 2`, the first :math:`m` elements of :math:`\mathrm{alpha}` are unchanged on exit.
.. _d01ar-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`2`)
On entry, :math:`\mathrm{iparm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{iparm} = 0`, :math:`1` or :math:`2`.
(`errno` :math:`3`)
The function was called with :math:`\mathrm{iparm} = 2`, but a previous call with :math:`\mathrm{iparm} = 1` has been omitted, or made with zero integration interval.
(`errno` :math:`4`)
The function was called with :math:`\mathrm{iparm} = 2`, but the interval for indefinite integration is not contained within the interval specified in the previous call with :math:`\mathrm{iparm} = 1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
All :math:`\mathrm{maxrul}` rules have been used but the integral has not converged to the accuracy requested. :math:`\mathrm{maxrul} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
Failure in convergence during the run with :math:`\mathrm{iparm} = 1` in which the Legendre expansion was created.
.. _d01ar-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``dim1_indef`` evaluates definite and indefinite integrals of the form:
.. math::
\int_a^bf\left(t\right){dt}
using the method described in Patterson (1968).
**Definite Integrals**
In this case ``dim1_indef`` must be called with :math:`\mathrm{iparm} = 0`.
By linear transformation the integral is changed to
.. math::
I = \int_{-1}^{+1}F\left(x\right){dx}
where
.. math::
F\left(x\right) = \frac{{b-a}}{2}f\left(\frac{{b+a+\left(b-a\right)x}}{2}\right)
and is then approximated by an :math:`n`-point quadrature rule
.. math::
I = \sum_{{k = 1}}^nw_kF\left(x_k\right)
where :math:`w_k` are the weights and :math:`x_k` are the abscissae.
The function uses a family of nine interlacing rules based on the optimal extension of the three-point Gauss rule.
These rules use :math:`1`, :math:`3`, :math:`7`, :math:`15`, :math:`31`, :math:`63`, :math:`127`, :math:`255` and :math:`511` points and have respective polynomial integrating degrees :math:`1`, :math:`5`, :math:`11`, :math:`23`, :math:`47`, :math:`95`, :math:`191`, :math:`383` and :math:`767`.
Each rule has the property that the next in sequence includes all the points of its predecessor and has the greatest possible increase in integrating degree.
The integration method is based on the successive application of these rules until the absolute value of the difference of two successive results differs by not more than :math:`\mathrm{absacc}`, or relatively by not more than :math:`\mathrm{relacc}`.
The result of the last rule used is taken as the value of the integral (:math:`\mathrm{ans}`), and the absolute difference of the results of the last two rules used is taken as an estimate of the absolute error (:math:`\mathrm{acc}`).
Due to their interlacing form no integrand evaluations are wasted in passing from one rule to the next.
**Indefinite Integrals**
Suppose the value of the integral
.. math::
\int_c^df\left(t\right){dt}
is required for a number of sub-intervals :math:`\left[c, d\right]`, all of which lie in an interval :math:`\left[a, b\right]`.
In this case ``dim1_indef`` should first be called with the argument :math:`\mathrm{iparm} = 1` and the interval set to :math:`\left[a, b\right]`.
The function then calculates the integral over :math:`\left[a, b\right]` **and** the Legendre expansion of the integrand, using the same integrand values.
If the function is subsequently called with :math:`\mathrm{iparm} = 2` and the interval set to :math:`\left[c, d\right]`, the integral over :math:`\left[c, d\right]` is calculated by analytical integration of the Legendre expansion, without further evaluations of the integrand.
For the interval :math:`\left[-1, 1\right]` the expansion takes the form
.. math::
F\left(x\right) = \sum_{{i = 0}}^{\infty }\alpha_iP_i\left(x\right)
where :math:`P_i\left(x\right)` is the order :math:`i` Legendre polynomial.
Assuming that the integral over the full range :math:`\left[-1, 1\right]` was evaluated to the required accuracy using an :math:`n`-point rule, then the coefficients
.. math::
\alpha_i = \frac{1}{2}\left(2i-1\right)\int_{-1}^{+1}P_i\left(x\right)F\left(x\right){dx}\text{, }\quad i = 0,1,\ldots,m
are evaluated by that same rule, up to
.. math::
m = \left(3n-1\right)/4\text{.}
The accuracy for indefinite integration should be of the same order as that obtained for the definite integral over the full range.
The indefinite integrals will be exact when :math:`F\left(x\right)` is a polynomial of degree :math:`\text{}\leq m`.
.. _d01ar-py2-py-references:
**References**
Patterson, T N L, 1968, `The Optimum addition of points to quadrature formulae`, Math. Comput. (22), 847--856
"""
raise NotImplementedError
[docs]def dim1_inf_wtrig(g, a, omega, key, epsabs, limlst=50, lw=800, liw=None, data=None):
r"""
``dim1_inf_wtrig`` calculates an approximation to the sine or the cosine transform of a function :math:`g` over :math:`\left[a, \infty \right)`:
.. math::
I = \int_a^{\infty }g\left(x\right)\sin\left(\omega x\right){dx}\quad \text{ or }\quad I = \int_a^{\infty }g\left(x\right)\cos\left(\omega x\right){dx}
(for a user-specified value of :math:`\omega`).
.. _d01as-py2-py-doc:
For full information please refer to the NAG Library document for d01as
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01asf.html
.. _d01as-py2-py-parameters:
**Parameters**
**g** : callable retval = g(x, data=None)
:math:`\mathrm{g}` must return the value of the function :math:`g` at a given point :math:`\mathrm{x}`.
**Parameters**
**x** : float
The point at which the function :math:`g` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`g\left(x\right)` evaluated at :math:`\mathrm{x}`.
**a** : float
:math:`a`, the lower limit of integration.
**omega** : float
The argument :math:`\omega` in the weight function of the transform.
**key** : int
Indicates which integral is to be computed.
:math:`\mathrm{key} = 1`
:math:`w\left(x\right) = \cos\left(\omega x\right)`.
:math:`\mathrm{key} = 2`
:math:`w\left(x\right) = \sin\left(\omega x\right)`.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01asf.html#accuracy>`__.
**limlst** : int, optional
An upper bound on the number of intervals :math:`C_k` needed for the integration.
**lw** : int, optional
The value of :math:`\mathrm{lw}` (together with that of :math:`\mathrm{liw}`) imposes a bound on the number of sub-intervals into which each interval :math:`C_k` may be divided by the function. The number of sub-intervals cannot exceed :math:`\mathrm{lw}/4`. The more difficult the integrand, the larger :math:`\mathrm{lw}` should be.
**liw** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`\mathrm{lw}/2`.
The number of sub-intervals into which each interval :math:`C_k` may be divided cannot exceed :math:`\mathrm{liw}/2`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**lst** : int
The number of intervals :math:`C_k` actually used for the integration.
**erlst** : float, ndarray, shape :math:`\left(\mathrm{limlst}\right)`
:math:`\mathrm{erlst}[\textit{k}-1]` contains the error estimate corresponding to the integral contribution over the interval :math:`C_{\textit{k}}`, for :math:`\textit{k} = 1,2,\ldots,\mathrm{lst}`.
**rslst** : float, ndarray, shape :math:`\left(\mathrm{limlst}\right)`
:math:`\mathrm{rslst}[\textit{k}-1]` contains the integral contribution over the interval :math:`C_{\textit{k}}`, for :math:`\textit{k} = 1,2,\ldots,\mathrm{lst}`.
**ierlst** : int, ndarray, shape :math:`\left(\mathrm{limlst}\right)`
:math:`\mathrm{ierlst}[\textit{k}-1]` contains the error flag corresponding to :math:`\mathrm{rslst}[\textit{k}-1]`, for :math:`\textit{k} = 1,2,\ldots,\mathrm{lst}`.
In the cases :math:`\mathrm{errno}` = 7, 8 or 9, additional information about the cause of the error can be obtained from the array :math:`\mathrm{ierlst}`, as follows:
:math:`\mathrm{ierlst}[k-1] = 1`
The maximum number of :math:`\text{subdivisions} = \mathrm{min}\left(\mathrm{lw}/4,\mathrm{liw}/2\right)` has been achieved on the :math:`k`\ th interval.
:math:`\mathrm{ierlst}[k-1] = 2`
Occurrence of round-off error is detected and prevents the tolerance imposed on the :math:`k`\ th interval from being achieved.
:math:`\mathrm{ierlst}[k-1] = 3`
Extremely bad integrand behaviour occurs at some points of the :math:`k`\ th interval.
:math:`\mathrm{ierlst}[k-1] = 4`
The integration procedure over the :math:`k`\ th interval does not converge (to within the required accuracy) due to round-off in the extrapolation procedure invoked on this interval. It is assumed that the result on this interval is the best which can be obtained.
:math:`\mathrm{ierlst}[k-1] = 5`
The integral over the :math:`k`\ th interval is probably divergent or slowly convergent. It must be noted that divergence can occur with any other value of :math:`\mathrm{ierlst}[k-1]`.
**iw** : int, ndarray, shape :math:`\left(\mathrm{liw}\right)`
:math:`\mathrm{iw}[0]` contains the maximum number of sub-intervals actually used for integrating over any of the intervals :math:`C_k`. The rest of the array is used as workspace.
.. _d01as-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`6`)
On entry, :math:`\mathrm{limlst} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{limlst}\geq 3`.
(`errno` :math:`6`)
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{key}\leq 2`.
(`errno` :math:`6`)
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{key}\geq 1`.
(`errno` :math:`10`)
On entry, :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{liw}\geq 2`.
(`errno` :math:`10`)
On entry, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{lw}\geq 4`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{LIMIT}`) has been reached: :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
(`errno` :math:`4`)
Round-off error is detected in the extrapolation table.
(`errno` :math:`5`)
The integral is probably divergent or slowly convergent.
(`errno` :math:`7`)
Bad integration behaviour occurs within interval :math:`\textit{K}`: :math:`\textit{K} = \langle\mathit{\boldsymbol{value}}\rangle`: :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`. Inspect :math:`\mathrm{ierlst}` for more details.
(`errno` :math:`8`)
The maximum number of intervals (:math:`\mathrm{limlst}`) has been reached: :math:`\mathrm{limlst} = \langle\mathit{\boldsymbol{value}}\rangle`. Inspect :math:`\mathrm{ierlst}` for more details.
(`errno` :math:`9`)
Extrapolation does not converge to the requested accuracy. Inspect :math:`\mathrm{ierlst}` for more details.
.. _d01as-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``dim1_inf_wtrig`` is based on the QUADPACK routine QAWFE (see Piessens `et al.` (1983)).
It is an adaptive function, designed to integrate a function of the form :math:`g\left(x\right)w\left(x\right)` over a semi-infinite interval, where :math:`w\left(x\right)` is either :math:`\sin\left(\omega x\right)` or :math:`\cos\left(\omega x\right)`.
Over successive intervals
.. math::
C_k = \left[{a+\left(k-1\right)c}, {a+kc}\right]\text{, }\quad k = 1,2,\ldots,\mathrm{lst}
integration is performed by the same algorithm as is used by :meth:`dim1_fin_wtrig`.
The intervals :math:`C_k` are of constant length
.. math::
c = \left\{2\left[\left\lvert \omega \right\rvert \right]+1\right\}\pi /\left\lvert \omega \right\rvert \text{, }\quad \omega \neq 0\text{,}
where :math:`\left[\left\lvert \omega \right\rvert \right]` represents the largest integer less than or equal to :math:`\left\lvert \omega \right\rvert`.
Since :math:`c` equals an odd number of half periods, the integral contributions over succeeding intervals will alternate in sign when the function :math:`g` is positive and monotonically decreasing over :math:`\left[a, \infty \right)`.
The algorithm, described in Piessens `et al.` (1983), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the :math:`\epsilon`-algorithm (see Wynn (1956)) to perform extrapolation.
The local error estimation is described by Piessens `et al.` (1983).
If :math:`\omega = 0` and :math:`\mathrm{key} = 1`, the function uses the same algorithm as :meth:`dim1_inf_general` (with :math:`{\textit{epsrel}} = 0.0`).
In contrast to the other functions in submodule ``quad``, ``dim1_inf_wtrig`` works only with an **absolute** error tolerance (:math:`\mathrm{epsabs}`).
Over the interval :math:`C_k` it attempts to satisfy the absolute accuracy requirement
.. math::
\textit{EPSA}_k = U_k\times \mathrm{epsabs}\text{,}
where :math:`U_{\textit{k}} = \left(1-p\right)p^{{\textit{k}-1}}`, for :math:`\textit{k} = 1,2,\ldots,` and :math:`p = 0.9`.
However, when difficulties occur during the integration over the :math:`k`\ th sub-interval :math:`C_k` such that the error flag :math:`\mathrm{ierlst}[k-1]` is nonzero, the accuracy requirement over subsequent intervals is relaxed.
See Piessens `et al.` (1983) for more details.
.. _d01as-py2-py-references:
**References**
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_fin_bad_vec(f, a, b, epsabs, epsrel, lw=800, liw=None, data=None):
r"""
``dim1_fin_bad_vec`` is a general purpose integrator which calculates an approximation to the integral of a function :math:`f\left(x\right)` over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{.}
.. deprecated:: 27.1.0.0
``dim1_fin_bad_vec`` will be removed in naginterfaces 31.3.0.0.
Please use :meth:`dim1_fin_general` instead.
See also the :ref:`Replacement Calls <replace>` document.
.. _d01at-py2-py-doc:
For full information please refer to the NAG Library document for d01at
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01atf.html
.. _d01at-py2-py-parameters:
**Parameters**
**f** : callable fv = f(x, data=None)
:math:`\mathrm{f}` must return the values of the integrand :math:`f` at a set of points.
**Parameters**
**x** : float, ndarray, shape :math:`\left(n\right)`
The points at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fv** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{fv}[\textit{j}-1]` must contain the value of :math:`f` at the point :math:`\mathrm{x}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01atf.html#accuracy>`__.
**epsrel** : float
The relative accuracy required. If :math:`\mathrm{epsrel}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01atf.html#accuracy>`__.
**lw** : int, optional
The value of :math:`\mathrm{lw}` (together with that of :math:`\mathrm{liw}`) imposes a bound on the number of sub-intervals into which the interval of integration may be divided by the function. The number of sub-intervals cannot exceed :math:`\mathrm{lw}/4`. The more difficult the integrand, the larger :math:`\mathrm{lw}` should be.
**liw** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`\mathrm{lw}/4`.
The number of sub-intervals into which the interval of integration may be divided cannot exceed :math:`\mathrm{liw}`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**w** : float, ndarray, shape :math:`\left(\mathrm{lw}\right)`
Details of the computation see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01atf.html#fcomments>`__ for more information.
**iw** : int, ndarray, shape :math:`\left(\mathrm{liw}\right)`
:math:`\mathrm{iw}[0]` contains the actual number of sub-intervals used. The rest of the array is used as workspace.
.. _d01at-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`6`)
On entry, :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{liw}\geq 1`.
(`errno` :math:`6`)
On entry, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{lw}\geq 4`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{LIMIT}`) has been reached: :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
(`errno` :math:`4`)
Round-off error is detected in the extrapolation table.
(`errno` :math:`5`)
The integral is probably divergent or slowly convergent.
.. _d01at-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``dim1_fin_bad_vec`` is based on the QUADPACK routine QAGS (see Piessens `et al.` (1983)).
It is an adaptive function, using the Gauss :math:`10`-point and Kronrod :math:`21`-point rules.
The algorithm, described in de Doncker (1978), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the :math:`\epsilon`-algorithm (see Wynn (1956)) to perform extrapolation.
The local error estimation is described in Piessens `et al.` (1983).
The function is suitable as a general purpose integrator, and can be used when the integrand has singularities, especially when these are of algebraic or logarithmic type.
``dim1_fin_bad_vec`` requires a function to evaluate the integrand at an array of different points and is, therefore, amenable to parallel execution.
Otherwise the algorithm is identical to that used by :meth:`dim1_fin_bad`.
.. _d01at-py2-py-references:
**References**
de Doncker, E, 1978, `An adaptive extrapolation algorithm for automatic integration`, ACM SIGNUM Newsl. (13(2)), 12--18
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_fin_osc_vec(f, a, b, epsabs, epsrel, key=6, lw=800, liw=None, data=None):
r"""
``dim1_fin_osc_vec`` is an adaptive integrator, especially suited to oscillating, nonsingular integrands, which calculates an approximation to the integral of a function :math:`f\left(x\right)` over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{.}
.. deprecated:: 27.1.0.0
``dim1_fin_osc_vec`` will be removed in naginterfaces 31.3.0.0.
Please use :meth:`dim1_fin_osc_fn` instead.
See also the :ref:`Replacement Calls <replace>` document.
.. _d01au-py2-py-doc:
For full information please refer to the NAG Library document for d01au
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01auf.html
.. _d01au-py2-py-parameters:
**Parameters**
**f** : callable fv = f(x, data=None)
:math:`\mathrm{f}` must return the values of the integrand :math:`f` at a set of points.
**Parameters**
**x** : float, ndarray, shape :math:`\left(n\right)`
The points at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fv** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{fv}[\textit{j}-1]` must contain the value of :math:`f` at the point :math:`\mathrm{x}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01auf.html#accuracy>`__.
**epsrel** : float
The relative accuracy required. If :math:`\mathrm{epsrel}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01auf.html#accuracy>`__.
**key** : int, optional
Indicates which integration rule is to be used.
:math:`\mathrm{key} = 1`
For the Gauss :math:`7`-point and Kronrod :math:`15`-point rule.
:math:`\mathrm{key} = 2`
For the Gauss :math:`10`-point and Kronrod :math:`21`-point rule.
:math:`\mathrm{key} = 3`
For the Gauss :math:`15`-point and Kronrod :math:`31`-point rule.
:math:`\mathrm{key} = 4`
For the Gauss :math:`20`-point and Kronrod :math:`41`-point rule.
:math:`\mathrm{key} = 5`
For the Gauss :math:`25`-point and Kronrod :math:`51`-point rule.
:math:`\mathrm{key} = 6`
For the Gauss :math:`30`-point and Kronrod :math:`61`-point rule.
**lw** : int, optional
The value of :math:`\mathrm{lw}` (together with that of :math:`\mathrm{liw}`) imposes a bound on the number of sub-intervals into which the interval of integration may be divided by the function. The number of sub-intervals cannot exceed :math:`\mathrm{lw}/4`. The more difficult the integrand, the larger :math:`\mathrm{lw}` should be.
**liw** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:`\mathrm{lw}/4`.
The number of sub-intervals into which the interval of integration may be divided cannot exceed :math:`\mathrm{liw}`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**w** : float, ndarray, shape :math:`\left(\mathrm{lw}\right)`
Details of the computation see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01auf.html#fcomments>`__ for more information.
**iw** : int, ndarray, shape :math:`\left(\mathrm{liw}\right)`
:math:`\mathrm{iw}[0]` contains the actual number of sub-intervals used. The rest of the array is used as workspace.
.. _d01au-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`4`)
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{key}\geq 1` and :math:`\mathrm{key}\leq 6`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{liw}\geq 1`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{lw}\geq 4`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{LIMIT}`) has been reached: :math:`\mathrm{LIMIT} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{lw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{liw} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
.. _d01au-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``dim1_fin_osc_vec`` is based on the QUADPACK routine QAG (see Piessens `et al.` (1983)).
It is an adaptive function, offering a choice of six Gauss--Kronrod rules.
A global acceptance criterion (as defined by Malcolm and Simpson (1976)) is used.
The local error estimation is described in Piessens `et al.` (1983).
Because ``dim1_fin_osc_vec`` is based on integration rules of high order, it is especially suitable for nonsingular oscillating integrands.
``dim1_fin_osc_vec`` requires a function to evaluate the integrand at an array of different points and is, therefore, amenable to parallel execution.
Otherwise this algorithm with :math:`\mathrm{key} = 6` is identical to that used by :meth:`dim1_fin_osc`.
.. _d01au-py2-py-references:
**References**
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, 1973, `An algorithm for automatic integration`, Angew. Inf. (15), 399--401
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
"""
raise NotImplementedError
[docs]def withdraw_dim1_gauss_wgen(itype, a, b, c, d, n):
r"""
``withdraw_dim1_gauss_wgen`` returns the weights (normal or adjusted) and abscissae for a Gaussian integration rule with a specified number of abscissae.
Six different types of Gauss rule are allowed.
.. deprecated:: 27.1.0.0
``withdraw_dim1_gauss_wgen`` will be removed in naginterfaces 31.3.0.0.
Please use :meth:`dim1_gauss_wgen` instead.
See also the :ref:`Replacement Calls <replace>` document.
.. _d01bc-py2-py-doc:
For full information please refer to the NAG Library document for d01bc
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01bcf.html
.. _d01bc-py2-py-parameters:
**Parameters**
**itype** : int
Indicates the type of quadrature rule.
:math:`\mathrm{itype} = 0`
Gauss--Legendre, with normal weights.
:math:`\mathrm{itype} = 1`
Gauss--Jacobi, with normal weights.
:math:`\mathrm{itype} = -1`
Gauss--Jacobi, with adjusted weights.
:math:`\mathrm{itype} = 2`
Exponential Gauss, with normal weights.
:math:`\mathrm{itype} = -2`
Exponential Gauss, with adjusted weights.
:math:`\mathrm{itype} = 3`
Gauss--Laguerre, with normal weights.
:math:`\mathrm{itype} = -3`
Gauss--Laguerre, with adjusted weights.
:math:`\mathrm{itype} = 4`
Gauss--Hermite, with normal weights.
:math:`\mathrm{itype} = -4`
Gauss--Hermite, with adjusted weights.
:math:`\mathrm{itype} = 5`
Rational Gauss, with normal weights.
:math:`\mathrm{itype} = -5`
Rational Gauss, with adjusted weights.
**a** : float
The parameter :math:`\mathrm{a}` which occurs in the quadrature formula
**b** : float
The parameter :math:`\mathrm{b}` which occurs in the quadrature formula
**c** : float
The parameter :math:`\mathrm{c}` which occurs in the quadrature formula
**d** : float
The parameter :math:`\mathrm{d}` which occurs in the quadrature formula
**n** : int
:math:`n`, the number of weights and abscissae to be returned. If :math:`\mathrm{itype} = -2` or :math:`-4` and :math:`\mathrm{c}\neq 0.0`, an odd value of :math:`\mathrm{n}` may raise problems (see :math:`\mathrm{errno}` = 6).
**Returns**
**weight** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
The :math:`\mathrm{n}` weights.
**abscis** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
The :math:`\mathrm{n}` abscissae.
.. _d01bc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`2`)
On entry, :math:`\mathrm{itype} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\left\lvert \mathrm{itype}\right\rvert < 6`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n} > 0`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{a}`, :math:`\mathrm{b}`, :math:`\mathrm{c}`, or :math:`\mathrm{d}` is not in the allowed range: :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle` :math:`\mathrm{c} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{d} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{itype} = \langle\mathit{\boldsymbol{value}}\rangle`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The algorithm for computing eigenvalues of a tridiagonal matrix has failed to converge.
(`errno` :math:`4`)
One or more of the weights are larger than :math:`\textit{rmax}`, the largest floating point number on this computer (see :meth:`machine.real_largest <naginterfaces.library.machine.real_largest>`): :math:`\textit{rmax} = \langle\mathit{\boldsymbol{value}}\rangle`.
Possible solutions are to use a smaller value of :math:`n`; or, if using adjusted weights to change to normal weights.
(`errno` :math:`5`)
One or more of the weights are too small to be distinguished from zero on this machine.
The underflowing weights are returned as zero, which may be a usable approximation.
Possible solutions are to use a smaller value of :math:`n`; or, if using normal weights, to change to adjusted weights.
(`errno` :math:`6`)
The contribution of the central abscissa to the summation is indeterminate.
.. _d01bc-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``withdraw_dim1_gauss_wgen`` returns the weights :math:`w_i` and abscissae :math:`x_i` for use in the summation
.. math::
S = \sum_{{i = 1}}^nw_if\left(x_i\right)
which approximates a definite integral (see Davis and Rabinowitz (1975) and Stroud and Secrest (1966)).
The following types are provided:
(a) Gauss--Legendre
.. math::
S\simeq \int_a^bf\left(x\right){dx}\text{, exact for }f\left(x\right) = P_{{2n-1}}\left(x\right)\text{.}
`Constraint:` :math:`b > a`.
(#) Gauss--Jacobi
normal weights:
.. math::
S\simeq \int_a^b\left(b-x\right)^c\left(x-a\right)^df\left(x\right){dx}\text{, exact for }f\left(x\right) = P_{{2n-1}}\left(x\right)\text{,}
adjusted weights:
.. math::
S\simeq \int_a^bf\left(x\right){dx}\text{, exact for }f\left(x\right) = \left(b-x\right)^c\left(x-a\right)^dP_{{2n-1}}\left(x\right)\text{.}
`Constraint:` :math:`c > -1`, :math:`d > -1`, :math:`b > a`.
(#) Exponential Gauss
normal weights:
.. math::
S\simeq \int_a^b\left\lvert x-\frac{{a+b}}{2}\right\rvert^cf\left(x\right){dx}\text{, exact for }f\left(x\right) = P_{{2n-1}}\left(x\right)\text{,}
adjusted weights:
.. math::
S\simeq \int_a^bf\left(x\right){dx}\text{, exact for }f\left(x\right) = \left\lvert x-\frac{{a+b}}{2}\right\rvert^cP_{{2n-1}}\left(x\right)\text{.}
`Constraint:` :math:`c > -1`, :math:`b > a`.
(#) Gauss--Laguerre
normal weights:
.. math::
\begin{array}{ll}S&\simeq \int_a^{\infty }\left\lvert x-a\right\rvert^ce^{{-bx}}f\left(x\right){dx}\quad \text{ }\quad \left(b > 0\right)\text{,}\\&\\&\simeq \int_{{-\infty }}^a\left\lvert x-a\right\rvert^ce^{{-bx}}f\left(x\right){dx}\quad \text{ }\quad \left(b < 0\right)\text{, exact for }f\left(x\right) = P_{{2n-1}}\left(x\right)\text{,}\end{array}
adjusted weights:
.. math::
\begin{array}{ll}S&\simeq \int_a^{\infty } f\left(x\right) {dx}\quad \text{ }\quad \left(b > 0\right)\text{,}\\&\\&\simeq \int_{{-\infty }}^a f\left(x\right) {dx}\quad \text{ }\quad \left(b < 0\right)\text{, exact for }f\left(x\right) = \left\lvert x-a\right\rvert^ce^{{-bx}}P_{{2n-1}}\left(x\right)\text{.}\end{array}
`Constraint:` :math:`c > -1`, :math:`b\neq 0`.
(#) Gauss--Hermite
normal weights:
.. math::
S\simeq \int_{{-\infty }}^{{+\infty }}\left\lvert x-a\right\rvert^ce^{{-b\left(x-a\right)^2}}f\left(x\right){dx}\text{, exact for }f\left(x\right) = P_{{2n-1}}\left(x\right)\text{,}
adjusted weights:
.. math::
S\simeq \int_{{-\infty }}^{{+\infty }}f\left(x\right){dx}\text{, exact for }f\left(x\right) = \left\lvert x-a\right\rvert^ce^{{-b\left(x-a\right)^2}}P_{{2n-1}}\left(x\right)\text{.}
`Constraint:` :math:`c > -1`, :math:`b > 0`.
(#) Rational Gauss
normal weights:
.. math::
\begin{array}{ll}S&\simeq \int_a^{\infty }\frac{\left\lvert x-a\right\rvert^c}{\left\lvert x+b\right\rvert^d}f\left(x\right){dx}\quad \text{ }\quad \left(a+b > 0\right)\text{,}\\&\\&\simeq \int_{{-\infty }}^a\frac{\left\lvert x-a\right\rvert^c}{\left\lvert x+b\right\rvert^d}f\left(x\right){dx}\quad \text{ }\quad \left(a+b < 0\right)\text{, exact for }f\left(x\right) = P_{{2n-1}} \left(\frac{1}{{x+b}}\right) \text{,}\end{array}
adjusted weights:
.. math::
\begin{array}{ll}S&\simeq \int_a^{\infty } f\left(x\right) {dx}\quad \text{ }\quad \left(a+b > 0\right)\text{,}\\&\\&\simeq \int_{{-\infty }}^a f\left(x\right) {dx}\quad \text{ }\quad \left(a+b < 0\right)\text{, exact for }f\left(x\right) = \frac{\left\lvert x-a\right\rvert^c}{\left\lvert x+b\right\rvert^d} P_{{2n-1}} \left(\frac{1}{{x+b}}\right) \text{.}\end{array}
`Constraint:` :math:`c > -1`, :math:`d > c+1`, :math:`a+b\neq 0`.
In the above formulae, :math:`P_{{2n-1}}\left(x\right)` stands for any polynomial of degree :math:`2n-1` or less in :math:`x`.
The method used to calculate the abscissae involves finding the eigenvalues of the appropriate tridiagonal matrix (see Golub and Welsch (1969)).
The weights are then determined by the formula
.. math::
w_i = \left\{\sum_{{j = 0}}^{{n-1}}P_j^*\left(x_i\right)^2\right\}^{-1}
where :math:`P_j^*\left(x\right)` is the :math:`j`\ th orthogonal polynomial with respect to the weight function over the appropriate interval.
The weights and abscissae produced by ``withdraw_dim1_gauss_wgen`` may be passed to :meth:`md_gauss`, which will evaluate the summations in one or more dimensions.
.. _d01bc-py2-py-references:
**References**
Davis, P J and Rabinowitz, P, 1975, `Methods of Numerical Integration`, Academic Press
Golub, G H and Welsch, J H, 1969, `Calculation of Gauss quadrature rules`, Math. Comput. (23), 221--230
Stroud, A H and Secrest, D, 1966, `Gaussian Quadrature Formulas`, Prentice--Hall
"""
raise NotImplementedError
[docs]def dim1_fin_smooth(f, a, b, epsabs, epsrel, data=None):
r"""
``dim1_fin_smooth`` calculates an approximation to the integral of a function over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{.}
It is non-adaptive and as such is recommended for the integration of 'smooth' functions.
These **exclude** integrands with singularities, derivative singularities or high peaks on :math:`\left[a, b\right]`, or which oscillate too strongly on :math:`\left[a, b\right]`.
.. _d01bd-py2-py-doc:
For full information please refer to the NAG Library document for d01bd
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01bdf.html
.. _d01bd-py2-py-parameters:
**Parameters**
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a given point.
**Parameters**
**x** : float
The point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`f\left(x\right)` evaluated at :math:`\mathrm{x}`.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
**epsabs** : float
The absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01bdf.html#accuracy>`__.
**epsrel** : float
The relative accuracy required. If :math:`\mathrm{epsrel}` is negative, the absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01bdf.html#accuracy>`__.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
.. _d01bd-py2-py-notes:
**Notes**
``dim1_fin_smooth`` is based on the QUADPACK routine QNG (see Piessens `et al.` (1983)).
It is a non-adaptive function which uses as its basic rules, the Gauss :math:`10`-point and :math:`21`-point formulae.
If the accuracy criterion is not met, formulae using :math:`43` and :math:`87` points are used successively, stopping whenever the accuracy criterion is satisfied.
This function is designed for smooth integrands only.
.. _d01bd-py2-py-references:
**References**
Patterson, T N L, 1968, `The Optimum addition of points to quadrature formulae`, Math. Comput. (22), 847--856
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
See Also
--------
:meth:`naginterfaces.library.examples.quad.dim1_fin_smooth_ex.main`
"""
raise NotImplementedError
[docs]def dim2_fin(ya, yb, phi1, phi2, f, absacc, data=None):
r"""
``dim2_fin`` attempts to evaluate a double integral to a specified absolute accuracy by repeated applications of the method described by Patterson (1968) and Patterson (1969).
.. _d01da-py2-py-doc:
For full information please refer to the NAG Library document for d01da
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01daf.html
.. _d01da-py2-py-parameters:
**Parameters**
**ya** : float
:math:`a`, the lower limit of the integral.
**yb** : float
:math:`b`, the upper limit of the integral. It is not necessary that :math:`a < b`.
**phi1** : callable retval = phi1(y, data=None)
:math:`\mathrm{phi1}` must return the lower limit of the inner integral for a given value of :math:`y`.
**Parameters**
**y** : float
The value of :math:`y` for which the lower limit must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The lower limit of the inner integral for the given value of :math:`y`.
**phi2** : callable retval = phi2(y, data=None)
:math:`\mathrm{phi2}` must return the upper limit of the inner integral for a given value of :math:`y`.
**Parameters**
**y** : float
The value of :math:`y` for which the upper limit must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The upper limit of the inner integral for the given value of :math:`y`.
**f** : callable retval = f(x, y, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a given point.
**Parameters**
**x** : float
The coordinates of the point :math:`\left(x, y\right)` at which the integrand :math:`f` must be evaluated.
**y** : float
The coordinates of the point :math:`\left(x, y\right)` at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`f\left(x\right)` evaluated at :math:`\mathrm{x}`.
**absacc** : float
The absolute accuracy requested.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**ans** : float
The estimated value of the integral.
**npts** : int
The total number of function evaluations.
.. _d01da-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`i \bmod 10 \neq 0`)
The outer integral has not converged, and :math:`n` of the inner integrals have not converged with :math:`255` points: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`. :math:`\mathrm{ans}` may still contain an approximate estimate of the integral, but its reliability will decrease as :math:`n` increases.
(`errno` :math:`i \bmod 10 = 0`)
The outer integral has converged, but :math:`n` of the inner integrals have not converged with :math:`255` points: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`. :math:`\mathrm{ans}` may still contain an approximate estimate of the integral, but its reliability will decrease as :math:`n` increases.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The outer integral has not converged with :math:`255` points. However, all the inner integrals have converged, and :math:`\mathrm{ans}` may still contain an approximate estimate of the integral.
.. _d01da-py2-py-notes:
**Notes**
``dim2_fin`` attempts to evaluate a definite integral of the form
.. math::
I = \int_a^b\int_{{\phi_1\left(y\right)}}^{{\phi_2\left(y\right)}}f\left(x, y\right){dx}{dy}
where :math:`a` and :math:`b` are constants and :math:`\phi_1\left(y\right)` and :math:`\phi_2\left(y\right)` are functions of the variable :math:`y`.
The integral is evaluated by expressing it as
.. math::
I = \int_a^bF\left(y\right){dy}\text{, where }\quad F\left(y\right) = \int_{{\phi_1\left(y\right)}}^{{\phi_2\left(y\right)}}f\left(x, y\right){dx}\text{.}
Both the outer integral :math:`I` and the inner integrals :math:`F\left(y\right)` are evaluated by the method, described by Patterson (1968) and Patterson (1969), of the optimum addition of points to Gauss quadrature formulae.
This method uses a family of interlacing common point formulae.
Beginning with the :math:`3`-point Gauss rule, formulae using :math:`7`, :math:`15`, :math:`31`, :math:`63`, :math:`127` and finally :math:`255` points are derived.
Each new formula contains all the points of the earlier formulae so that no function evaluations are wasted.
Each integral is evaluated by applying these formulae successively until two results are obtained which differ by less than the specified absolute accuracy.
.. _d01da-py2-py-references:
**References**
Patterson, T N L, 1968, `On some Gauss and Lobatto based integration formulae`, Math. Comput. (22), 877--881
Patterson, T N L, 1969, `The optimum addition of points to quadrature formulae, errata`, Math. Comput. (23), 892
"""
raise NotImplementedError
[docs]def md_adapt_multi(a, b, mincls, maxcls, nfun, funsub, absreq, relreq, wrkstr, data=None):
r"""
``md_adapt_multi`` computes approximations to the integrals of a vector of similar functions, each defined over the same multidimensional hyper-rectangular region.
The function uses an adaptive subdivision strategy, and also computes absolute error estimates.
.. _d01ea-py2-py-doc:
For full information please refer to the NAG Library document for d01ea
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01eaf.html
.. _d01ea-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
The lower limits of integration, :math:`a_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
**b** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
The upper limits of integration, :math:`b_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
**mincls** : int
Must be set either to the minimum number of :math:`\mathrm{funsub}` calls to be allowed, in which case :math:`\mathrm{mincls}\geq 0` or to a negative value. In this case, the function continues the calculation started in a previous call with the same integrands and integration limits: no arguments other than :math:`\mathrm{mincls}`, :math:`\mathrm{maxcls}`, :math:`\mathrm{absreq}` or :math:`\mathrm{relreq}` must be changed between the calls.
**maxcls** : int
The maximum number of :math:`\mathrm{funsub}` calls to be allowed. In the continuation case this is the number of new :math:`\mathrm{funsub}` calls to be allowed.
**nfun** : int
:math:`m`, the number of integrands.
**funsub** : callable f = funsub(z, nfun, data=None)
:math:`\mathrm{funsub}` must evaluate the integrands :math:`f_i` at a given point.
**Parameters**
**z** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The coordinates of the point at which the integrands must be evaluated.
**nfun** : int
:math:`m`, the number of integrands.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**f** : float, array-like, shape :math:`\left(\mathrm{nfun}\right)`
The value of the :math:`i`\ th integrand at the given point.
**absreq** : float
The absolute accuracy required by you.
**relreq** : float
The relative accuracy required by you.
**wrkstr** : float, array-like, shape :math:`\left(\textit{lenwrk}\right)`
If :math:`\mathrm{mincls} < 0`, :math:`\mathrm{wrkstr}` must be unchanged from the previous call of ``md_adapt_multi``.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**mincls** : int
Gives the number of :math:`\mathrm{funsub}` calls actually used by ``md_adapt_multi``. For the continuation case (:math:`\mathrm{mincls} < 0` on entry) this is the number of new :math:`\mathrm{funsub}` calls on the current call to ``md_adapt_multi``.
**wrkstr** : float, ndarray, shape :math:`\left(\textit{lenwrk}\right)`
Contains information about the current subdivision which could be used in a continuation call.
**finest** : float, ndarray, shape :math:`\left(\mathrm{nfun}\right)`
:math:`\mathrm{finest}[\textit{i}-1]` specifies the best estimate obtained from the :math:`\textit{i}`\ th integral, for :math:`\textit{i} = 1,2,\ldots,m`.
**absest** : float, ndarray, shape :math:`\left(\mathrm{nfun}\right)`
:math:`\mathrm{absest}[\textit{i}-1]` specifies the estimated absolute accuracy of :math:`\mathrm{finest}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,m`.
.. _d01ea-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`4`)
On entry, :math:`\mathrm{maxcls} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`R = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{maxcls}\geq R = 1+\textit{ndim}\times \left(4\times \textit{ndim}^2-6\times \textit{ndim}+14\right)/3`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{maxcls} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`R = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{maxcls}\geq R = 2^{\textit{ndim}}+2\times \textit{ndim}^2+2\times \textit{ndim}+1`.
(`errno` :math:`4`)
On entry, :math:`\textit{lenwrk}` is too small. :math:`\textit{lenwrk} = \langle\mathit{\boldsymbol{value}}\rangle`. Minimum possible dimension: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{maxcls} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{mincls} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{maxcls}\geq \mathrm{mincls}`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{nfun} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nfun}\geq 1`.
(`errno` :math:`4`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ndim}\geq 1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
:math:`\mathrm{maxcls}` too small to obtain required accuracy. :math:`\mathrm{maxcls} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
:math:`\textit{lenwrk}` too small for the function to continue. :math:`\textit{lenwrk} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
:math:`\mathrm{maxcls}` too small to make any progress. :math:`\mathrm{maxcls} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _d01ea-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``md_adapt_multi`` uses a globally adaptive method based on the algorithm described by van Dooren and de Ridder (1976) and Genz and Malik (1980).
It is implemented for integrals in the form:
.. math::
\int_{a_1}^{{b_1}}\int_{a_2}^{{b_2}}\ldots \int_{a_n}^{{b_n}}\left(f_1, f_2, \ldots, f_m\right){dx_n}\ldots {dx_2}dx_1\text{,}
where :math:`f_i = f_i\left(x_1, x_2, \ldots, x_n\right)`, for :math:`i = 1,2,\ldots,m`.
Upon entry, unless :math:`\mathrm{mincls}` has been set to a value less than or equal to :math:`0`, ``md_adapt_multi`` divides the integration region into a number of subregions with randomly selected volumes.
Inside each subregion the integrals and their errors are estimated.
The initial number of subregions is chosen to be as large as possible without using more than :math:`\mathrm{mincls}` calls to :math:`\mathrm{funsub}`.
The results are stored in a partially ordered list (a heap).
The function then proceeds in stages.
At each stage the subregion with the largest error (measured using the maximum norm) is halved along the coordinate axis where the integrands have largest absolute fourth differences.
The basic rule is applied to each half of this subregion and the results are stored in the list.
The results from the two halves are used to update the global integral and error estimates (:math:`\mathrm{finest}` and :math:`\mathrm{absest}`) and the function continues unless :math:`\left\lVert \mathrm{absest}\right\rVert \leq \mathrm{max}\left(\mathrm{absreq}, {\left\lVert \mathrm{finest}\right\rVert \times \mathrm{relreq}}\right)` where the norm :math:`\left\lVert.\right\rVert` is the maximum norm, or further subdivision would use more than :math:`\mathrm{maxcls}` calls to :math:`\mathrm{funsub}`.
If at some stage there is insufficient working storage to keep the results for the next subdivision, the function switches to a less efficient mode; only if this mode of operation breaks down is insufficient storage reported.
.. _d01ea-py2-py-references:
**References**
Genz, A C and Malik, A A, 1980, `An adaptive algorithm for numerical integration over an N-dimensional rectangular region`, J. Comput. Appl. Math. (6), 295--302
van Dooren, P and de Ridder, L, 1976, `An adaptive algorithm for numerical integration over an N-dimensional cube`, J. Comput. Appl. Math. (2), 207--217
"""
raise NotImplementedError
[docs]def md_sgq_multi_vec(ni, f, maxdlv, comm, data=None, spiked_sorder='C'):
r"""
``md_sgq_multi_vec`` approximates a vector of definite integrals :math:`\mathbf{F}` over the unit hypercube :math:`\Omega = \left[0, 1\right]^d`, given the vector of integrands :math:`\mathbf{f}\left(\mathbf{x}\right)`.
.. math::
\mathbf{F} = \int_{\Omega }\mathbf{f}\left(\mathbf{x}\right)d\mathbf{x} = \int_0^1\int_0^1\ldots \int_0^1\mathbf{f}\left(x_1, x_2, \ldots, x_d\right)d_{x_1}d_{x_2}\ldots d_{x_d}\text{.}
The function uses a sparse grid discretisation, allowing for computationally feasible estimations of integrals of high dimension (:math:`d\sim O\left(100\right)`).
Note: this function uses optional algorithmic parameters, see also: :meth:`opt_set`, :meth:`opt_get`.
.. _d01es-py2-py-doc:
For full information please refer to the NAG Library document for d01es
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01esf.html
.. _d01es-py2-py-parameters:
**Parameters**
**ni** : int
:math:`n_i`, the number of integrands.
**f** : callable (fm, iflag) = f(ni, ndim, xtr, icolzp, irowix, xs, qs, iflag, data=None)
:math:`\mathrm{f}` must return the value of the integrands :math:`f_j` at a set of :math:`n_x` :math:`d`-dimensional points :math:`\mathbf{x}_i`, implicitly supplied as columns of a matrix :math:`X\left(d, n_x\right)`.
If :math:`X` was supplied explicitly you would find that most of the elements attain the same value, :math:`x_{\textit{tr}}`; the larger the number of dimensions, the greater the proportion of elements of :math:`X` would be equal to :math:`x_{\textit{tr}}`.
So, :math:`X` is effectively a sparse matrix, except that the 'zero' elements are replaced by elements that are all equal to the value :math:`x_{{\textit{tr}}}`.
For this reason :math:`X` is supplied, as though it were a sparse matrix, in compressed column storage (CCS) format (see `the F11 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11intro.html>`__).
Individual entries :math:`x_{{\textit{k},i}}` of :math:`X`, for :math:`\textit{k} = 1,2,\ldots,d`, are either trivially valued, in which case :math:`x_{{k,i}} = x_{{\textit{tr}}}`, or are non-trivially valued.
For point :math:`i`, the non-trivial row indices and corresponding abscissae values are supplied in elements :math:`c\left(\textit{i}\right) = \mathrm{icolzp}[\textit{i}-1],\ldots,\mathrm{icolzp}[\textit{i}]-1`, for :math:`\textit{i} = 1,2,\ldots,n_x`, of the arrays :math:`\mathrm{irowix}` and :math:`\mathrm{xs}`, respectively.
Hence the :math:`i`\ th column of the matrix :math:`X` is retrievable as
.. math::
\begin{array}{l} X \left(\mathrm{irowix}[ c\left(i\right) -1], i\right) = \mathrm{xs}[ c\left(i\right) -1] \text{,} \\\\ X \left({k \notin \mathrm{irowix}[ {c\left(i\right)} -1]}, i\right) = x_{{\textit{tr}}} \text{.} \end{array}
An equivalent integer valued matrix :math:`\textit{Q}` is also implicitly provided.
This contains the unique indices :math:`q_{{k,i}}` of the underlying one-dimensional quadrature rule corresponding to the individual abscissae :math:`x_{{k,i}}`.
For trivial abscissae, the implicit index :math:`q_{{k,i}} = 1`. :math:`\textit{Q}` is supplied in the same CCS format as :math:`X`, with the non-trivial values supplied in :math:`\mathrm{qs}`.
**Parameters**
**ni** : int
:math:`n_i`, the number of integrands.
**ndim** : int
:math:`\textit{d}`, the number of dimensions.
**xtr** : float
:math:`x_{\textit{tr}}`, the value of the trivial elements of :math:`X`.
**icolzp** : int, ndarray, shape :math:`\left(\textit{nx}+1\right)`
The set :math:`\left\{\mathrm{icolzp}[\textit{i}-1],\ldots,\mathrm{icolzp}[\textit{i}]-1\right\}` contains the indices of :math:`\mathrm{irowix}` and :math:`\mathrm{xs}` corresponding to the non-trivial elements of column :math:`\textit{i}` of :math:`X` and hence of the point :math:`\mathbf{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
**irowix** : int, ndarray, shape :math:`\left(\textit{nntr}\right)`
The row indices corresponding to the non-trivial elements of :math:`X`.
**xs** : float, ndarray, shape :math:`\left(\textit{nntr}\right)`
:math:`x_{{k,i}}\neq x_{\textit{tr}}`, the non-trivial entries of :math:`X`.
**qs** : int, ndarray, shape :math:`\left(\textit{nntr}\right)`
:math:`q_{{k,i}}\neq 1`, the indices of the underlying quadrature rules corresponding to :math:`x_{{k,i}}\neq x_{\textit{tr}}`.
**iflag** : int
If :math:`\mathrm{iflag} = 0`, this is the first call to :math:`\mathrm{f}`. :math:`n_x = 1`, and the entire point :math:`\mathbf{x}_1` will satisfy :math:`x_{{\textit{k},1}} = x_{{\textit{tr}}}`, for :math:`\textit{k} = 1,2,\ldots,d`. In addition, :math:`\textit{nntr}` contains the total number of abscissae from the underlying one-dimensional quadrature; :math:`\mathrm{xs}` contains the complete set of abscissae and :math:`\mathrm{qs}` contains the corresponding quadrature indices, with :math:`\mathrm{xs}[0] = x_{{\textit{tr}}}` and :math:`\mathrm{qs}[0] = 1`. This will always be called in serial.
In subsequent calls to :math:`\mathrm{f}`, :math:`\mathrm{iflag} = 1`.
Subsequent calls may be made from within an OpenMP parallel region.
See `Parallelism and Performance <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01esf.html#parallel>`__ for details.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fm** : float, array-like, shape :math:`\left(\mathrm{ni}, \textit{nx}\right)`
:math:`\mathrm{fm}[\textit{p}-1,\textit{i}-1] = f_{\textit{p}}\left(\mathbf{x}_{\textit{i}}\right)`, for :math:`\textit{p} = 1,2,\ldots,n_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
**iflag** : int
Set :math:`\mathrm{iflag} < 0` if you wish to force an immediate exit from ``md_sgq_multi_vec`` with :math:`\mathrm{errno}` = -1.
**maxdlv** : int, array-like, shape :math:`\left(\textit{ndim}\right)`
:math:`\mathbf{m}`, the array of maximum levels for each dimension. :math:`\mathrm{maxdlv}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,d`, contains :math:`m_{\textit{j}}`, the maximum level of quadrature rule dimension j will support.
The default value, :math:`\mathrm{min}\left(m_q, L\right)` will be used if either :math:`\mathrm{maxdlv}[j-1]\leq 0` or :math:`\mathrm{maxdlv}[j-1]\geq \mathrm{min}\left({m_q}, L\right)` (for details on the default values for :math:`m_q` and :math:`L` and on how to change these values see the options 'Maximum Level', 'Maximum Quadrature Level' and 'Quadrature Rule').
If :math:`\mathrm{maxdlv}[j-1] = 1` for all :math:`j`, only one evaluation will be performed, and as such no error estimation will be possible.
Note: setting non-default values for some dimensions makes the assumption that the contribution from the omitted subspaces is :math:`0`. The integral and error estimates will only be based on included subspaces, which if the :math:`0` contribution assumption is not valid will be erroneous.
`Suggested value`: :math:`\mathrm{maxdlv}[j-1] = 0` for all :math:`j = 1,2,\ldots,d`.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`opt_set`.
**data** : arbitrary, optional
User-communication data for callback functions.
**spiked_sorder** : str, optional
If :math:`\mathrm{fm}` in :math:`\mathrm{f}` is spiked (i.e., has unit extent in all but one dimension, or has size :math:`1`), :math:`\mathrm{spiked\_sorder}` selects the storage order to associate with it in the NAG Engine:
spiked_sorder = :math:`\texttt{'C'}`
row-major storage will be used;
spiked_sorder = :math:`\texttt{'F'}`
column-major storage will be used.
**Returns**
**dinest** : float, ndarray, shape :math:`\left(\mathrm{ni}\right)`
:math:`\mathrm{dinest}[\textit{p}-1]` contains the final estimate :math:`\hat{F}_{\textit{p}}` of the definite integral :math:`F_p`, for :math:`\textit{p} = 1,2,\ldots,n_i`.
**errest** : float, ndarray, shape :math:`\left(\mathrm{ni}\right)`
:math:`\mathrm{errest}[\textit{p}-1]` contains the final error estimate :math:`E_p` of the definite integral :math:`F_p`, for :math:`\textit{p} = 1,2,\ldots,n_i`.
**ivalid** : int, ndarray, shape :math:`\left(\mathrm{ni}\right)`
:math:`\mathrm{ivalid}[\textit{p}-1]` indicates the final state of integral :math:`\textit{p}`, for :math:`\textit{p} = 1,2,\ldots,n_i`.
:math:`\mathrm{ivalid}[p-1] = 0`
The error estimate for integral :math:`p` was below the requested tolerance.
:math:`\mathrm{ivalid}[p-1] = 1`
The error estimate for integral :math:`p` was below the requested tolerance. The final level used was non-isotropic.
:math:`\mathrm{ivalid}[p-1] = 2`
The error estimate for integral :math:`p` was above the requested tolerance.
:math:`\mathrm{ivalid}[p-1] = 3`
The error estimate for integral :math:`p` was above :math:`\mathrm{max}\left({0.1\left\lvert \hat{F}_p\right\rvert }, 0.01\right)`.
:math:`\mathrm{ivalid}[p-1] < 0`
You aborted the evaluation before an error estimate could be made.
.. _d01es-py2-py-other_params:
**Other Parameters**
**'Absolute Tolerance'** : float
Default :math:`\text{} = \sqrt{\epsilon }`
:math:`r = \epsilon_a`, the absolute tolerance required.
**'Index Level'** : int
Default :math:`\text{} = 4`
The maximum level at which function values are stored for later use.
Larger values use increasingly more memory, and require more time to access specific elements.
Lower levels result in more repeated computation.
The 'Maximum Quadrature Level', :math:`m_q` is the effective upper limit on 'Index Level'.
If :math:`i\geq m_q`, ``md_sgq_multi_vec`` will use :math:`m_q` as the value of 'Index Level'.
Constraint: :math:`i\geq 1`.
**'Maximum Level'** : int
Default :math:`\text{} = 5`
:math:`i = L`, the maximum number of levels to evaluate.
Constraint: :math:`1 < i\leq 20`.
Note: the maximum allowable level in any single dimension, :math:`m_q`, is governed by the 'Quadrature Rule' selected. If a value greater than :math:`m_q` is set, only a subset of subspaces from higher levels will be used. Should this subset be empty for a given level, computation will consider the preceding level to be the maximum level and will terminate.
**'Maximum Nx'** : int
Default :math:`\text{} = 128`
:math:`i = \mathrm{max}\textit{n}_x`, the maximum number of points to evaluate in a single call to :math:`\mathrm{f}`.
Constraint: :math:`1\leq i\leq 16384`.
**'Maximum Quadrature Level'** : int
Queriable only
:math:`i = m_q`, the maximum level of the underlying one-dimensional quadrature rule (see 'Quadrature Rule').
**'Minimum Level'** : int
Default :math:`\text{} = 2`
The minimum number of levels which must be evaluated before an error estimate is used to determine convergence.
Constraint: :math:`i > 1`.
Note: if the minimum level is greater than the maximum computable level, the maximum level will be used.
**'Quadrature Rule'** : str
Default :math:`\text{} = \texttt{'Gauss-Patterson'}`
The underlying one-dimensional quadrature rule to be used in the construction.
Open rules do not require evaluations at boundaries.
:math:`\text{‘Quadrature Rule'} = \texttt{'Gauss-Patterson'}` or :math:`\texttt{'GP'}`
The interlacing Gauss--Patterson rules. Level :math:`\ell` uses :math:`2^{\ell }-1` abscissae. All levels are open. These rules provide high order accuracy. :math:`m_q = 9`.
:math:`\text{‘Quadrature Rule'} = \texttt{'Clenshaw-Curtis'}` or :math:`\texttt{'CC'}`
The interlacing Clenshaw--Curtis rules. Level :math:`\ell` uses :math:`2^{{\ell -1}}+1` abscissae. All levels above level :math:`1` are closed. :math:`m_q = 12`.
**'Relative Tolerance'** : float
Default :math:`\text{} = \sqrt{\epsilon }`
:math:`r = \epsilon_a`, the relative tolerance required.
**'Summation Precision'** : str
Default :math:`\text{} = \texttt{'HIGHER'}`
Determines whether ``md_sgq_multi_vec`` uses working precision or higher-than-working precision to accumulate the actions over subspaces.
:math:`\text{‘Summation Precision'} = \texttt{'HIGHER'}` or :math:`\texttt{'H'}`
Higher-than-working precision is used to accumulate the action over a subspace, and for the accumulation of all such actions. This is more expensive computationally, although this is probably negligible in comparison to the cost of evaluating the integrands and the overall runtime. This significantly reduces variation in the result when changing the number of threads.
:math:`\text{‘Summation Precision'} = \texttt{'WORKING'}` or :math:`\texttt{'W'}`
Working precision is used to accumulate the actions over subspaces. This may provide some speedup, particularly if :math:`n_i` or :math:`n_t` is large. The results of parallel simulations will however be more prone to variation.
**'Serial Levels'** : int
Default :math:`\text{} = 1`
:math:`i = s_l`, the number of levels to be evaluated in serial before initializing parallelization.
For relatively trivial integrands, this may need to be set greater than the default to reduce parallel overhead.
.. _d01es-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`11`)
On entry, :math:`\mathrm{ni} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ni}\geq 1`.
(`errno` :math:`21`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ndim}\geq 1`.
(`errno` :math:`1001`)
Either the option arrays :math:`\mathrm{comm}`\ ['iopts'] and :math:`\mathrm{comm}`\ ['opts'] have not been initialized for ``md_sgq_multi_vec``, or they have become corrupted.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`-1`)
Exit requested from :math:`\mathrm{f}` with :math:`\mathrm{iflag} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
The requested accuracy was not achieved for at least one integral.
(`errno` :math:`2`)
No accuracy was achieved for at least one integral.
.. _d01es-py2-py-notes:
**Notes**
``md_sgq_multi_vec`` uses a sparse grid to generate a vector of approximations :math:`\hat{\mathbf{F}}` to a vector of integrals :math:`\mathbf{F}` over the unit hypercube :math:`\Omega = \left[0, 1\right]^d`, that is,
.. math::
\hat{\mathbf{F}}≈\mathbf{F} = \int_{\left[0, 1\right]^d}\mathbf{f}\left(\mathbf{x}\right)d\mathbf{x}\text{.}
**Comparing Quadrature Over Full and Sparse Grids**
Before illustrating the sparse grid construction, it is worth comparing integration over a sparse grid to integration over a full grid.
Given a one-dimensional quadrature rule with :math:`N` abscissae, which accurately evaluates a polynomial of order :math:`P_N`, a full tensor product over :math:`d` dimensions, a full grid, may be constructed with :math:`N^d` multidimensional abscissae.
Such a product will accurately integrate a polynomial where the maximum power of any dimension is :math:`P_N`.
For example if :math:`d = 2` and :math:`P_N = 3`, such a rule will accurately integrate any polynomial whose highest order term is :math:`x_1^3x_2^3`.
Such a polynomial may be said to have a maximum combined order of :math:`P_N^d`, provided no individual dimension contributes a power greater than :math:`P_N`.
However, the number of multidimensional abscissae, or points, required increases exponentially with the dimension, rapidly making such a construction unusable.
The sparse grid technique was developed by Smolyak (Smolyak (1963)).
In this, multiple one-dimensional quadrature rules of increasing accuracy are combined in such a way as to provide a multidimensional quadrature rule which will accurately evaluate the integral of a polynomial whose maximum order appears as a monomial.
Hence a sparse grid construction whose highest level quadrature rule has polynomial order :math:`P_N` will accurately integrate a polynomial whose maximum combined order is also :math:`P_N`.
Again taking :math:`P_N = 3`, one may, theoretically, accurately integrate a polynomial such as :math:`x^3+x^2y+y^3`, but not a polynomial such as :math:`x^3y^3+xy`.
Whilst this has a lower maximum combined order than the full tensor product, the number of abscissae required increases significantly slower than the equivalent full grid, making some classes of integrals of dimension :math:`d\sim \mathrm{O}\left(100\right)` tractable.
Specifically, if a one-dimensional quadrature rule of level :math:`\ell` has :math:`N\sim \mathrm{O}\left(2^{\ell }\right)` abscissae, the corresponding full grid will have :math:`\mathrm{O}\left(\left(2^{\ell }\right)^d\right)` multidimensional abscissae, whereas the sparse grid will have :math:`\mathrm{O}\left(2^{\ell }{d}^{{\ell -1}}\right)`. Figure [label omitted] demonstrates this using a Gauss--Patterson rule with :math:`15` points in :math:`3` dimensions.
The full grid requires :math:`3375` points, whereas the sparse grid only requires :math:`111`.
[figure omitted]
**Sparse Grid Quadrature**
We now include a brief description of the sparse grid construction, sufficient for the understanding of the use of this routine.
For a more detailed analysis, see Gerstner and Griebel (1998).
Consider a one-dimensional :math:`n_{\ell }`-point quadrature rule of level :math:`\ell`, :math:`Q_{\ell }`.
The action of this rule on a integrand :math:`f` is to approximate its definite one-dimensional integral :math:`{}_1 F` as,
.. math::
{}_1 F = \int_0^1f\left(x\right)dx≈Q_{\ell }\left(f\right) = \sum_{1}^{n_{\ell }}{w_{{\ell,i}}\times f\left(x_{{\ell,i}}\right)}\text{,}
using weights :math:`w_{{\ell,i}}` and abscissae :math:`x_{{\ell,i}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\ell }`.
Now construct a set of one-dimensional quadrature rules, :math:`\left\{Q_{\ell } | \ell = 1,\ldots,L\right\}`, such that the accuracy of the quadrature rule increases with the level number.
In this routine we exclusively use quadrature rules which are completely nested, implying that if an abscissae :math:`x_{{\ell,k}}` is in level :math:`\ell`, it is also in level :math:`\ell +1`.
The quantity :math:`L` denotes some maximum level appropriate to the rules that have been selected.
Now define the action of the tensor product of :math:`d` rules as,
.. math::
\left(Q_{\ell_1}⊗ \cdots ⊗Q_{\ell_d}\right)\left(f\right) = \sum_{1}^{n_{\ell_1}}{ \cdots }\sum_{1}^{n_{\ell_d}}{w_{{\ell_1,i_1}} \cdots w_{{\ell_d,i_d}}}f\left(x_{{\ell_1,i_1}}, \ldots, x_{{\ell_d,i_d}}\right)\text{,}
where the individual level indices :math:`\ell_j` are not necessarily ordered or unique.
Each tensor product of :math:`d` rules defines an action of the quadrature rules :math:`Q_{\ell }`, :math:`\ell = \left(\ell_1,\ell_2,\ldots,\ell_d\right)` over a subspace, which is given a level :math:`\left\lvert \ell \right\rvert = \sum_{1}^{d}{\ell_j}`.
If all rule levels are equal, this is the full tensor product of that level.
The sparse grid construction of level :math:`\ell` can then be declared as the sum of all actions of the quadrature differences :math:`\Delta_k = \left(Q_k-Q_{{k-1}}\right)`, over all subspaces having a level at most :math:`\ell -d+1`,
.. math::
{}_d F≈Q_{\ell }^d\left(f\right) = \sum_{{\text{level at most }\ell -d+1}}\left(\Delta_{k_1}⊗ \cdots ⊗\Delta_{k_d}\right)\left(f\right)\text{.}
By definition, all subspaces used for level :math:`\ell -1` must also be used for level :math:`\ell`, and as such the difference between the result of all actions over subsequent sparse grid constructions may be used as an error estimate.
Let :math:`L` be the maximum level allowable in a sparse grid construction.
The classical sparse grid construction of :math:`\ell = L` allows each dimension to support a one-dimensional quadrature rule of level at most :math:`L`, with such a quadrature rule being used in every dimension at least once.
Such a construction lends equal weight to each dimension of the integration, and is termed here 'isotropic'.
Define the set :math:`\mathbf{m} = \left(m_j, {j = 1,2,\ldots,d}\right)`, where :math:`m_j` is the maximum quadrature rule allowed in the :math:`j`\ th dimension, and :math:`m_q` to be the maximum quadrature rule used by any dimension.
Let a subspace be identified by its quadrature difference levels, :math:`\mathbf{k} = \left(k_1, k_2, \ldots, k_d\right)`.
The classical construction may be extended by allowing different dimensions to have different values :math:`m_j`, and by allowing :math:`m_q\leq L`.
This creates non-isotropic constructions.
These are especially useful in higher dimensions, where some dimensions contribute more than others to the result, as they can drastically reduce the number of function evaluations required.
For example, consider the two-dimensional construction with :math:`L = 4`.
The classical isotropic construction would have the following subspaces.
Subspaces generated by a classical sparse grid with :math:`L = 4`.
.. rst-class:: nag-rules-none nag-align-left
+---------+----------------------------------------------------------------------------------------------------------+
|Level |Subspaces |
+=========+==========================================================================================================+
|:math:`1`|:math:`\left(1, 1\right)` |
+---------+----------------------------------------------------------------------------------------------------------+
|:math:`2`|:math:`\left(2, 1\right)`, :math:`\left(1, 2\right)` |
+---------+----------------------------------------------------------------------------------------------------------+
|:math:`3`|:math:`\left(3, 1\right)`, :math:`\left(2, 2\right)`, :math:`\left(1, 3\right)` |
+---------+----------------------------------------------------------------------------------------------------------+
|:math:`4`|:math:`\left(4, 1\right)`, :math:`\left(3, 2\right)`, :math:`\left(2, 3\right)`, :math:`\left(1, 4\right)`|
+---------+----------------------------------------------------------------------------------------------------------+
If the variation in the second dimension is sufficiently accurately described by a quadrature rule of level :math:`2`, the contributions of the subspaces :math:`\left(1, 3\right)` and :math:`\left(1, 4\right)` are probably negligible.
Similarly, if the variation in the first dimension is sufficiently accurately described by a quadrature rule of level :math:`3`, the subspace :math:`\left(4, 1\right)` is probably negligible.
Furthermore the subspace :math:`\left(2, 3\right)` would also probably have negligible impact, whereas the subspaces :math:`\left(2, 2\right)` and :math:`\left(3, 2\right)` would not.
Hence restricting the first dimension to a maximum level of :math:`3`, and the second dimension to a maximum level of :math:`2` would probably give a sufficiently acceptable estimate, and would generate the following subspaces.
Subspaces generated by a non-isotropic sparse grid with :math:`L = 4`, :math:`m_q = 3` and :math:`\mathbf{m} = \left(3, 2\right)`.
.. rst-class:: nag-rules-none nag-align-left
+---------+----------------------------------------------------+
|Level |Subspaces |
+=========+====================================================+
|:math:`1`|:math:`\left(1, 1\right)` |
+---------+----------------------------------------------------+
|:math:`2`|:math:`\left(2, 1\right)`, :math:`\left(1, 2\right)`|
+---------+----------------------------------------------------+
|:math:`3`|:math:`\left(3, 1\right)`, :math:`\left(2, 2\right)`|
+---------+----------------------------------------------------+
|:math:`4`|:math:`\left(4, 1\right)`, :math:`\left(3, 2\right)`|
+---------+----------------------------------------------------+
Taking this to the extreme, if the variation in the first and second dimensions are sufficiently accurately described by a level :math:`2` quadrature rule, restricting the maximum level of both dimensions to :math:`2` would generate the following subspaces.
Subspaces generated by a sparse grid construction with :math:`L = 4`, :math:`m_q = 2` and :math:`\mathbf{m} = \left(2, 2\right)`.
.. rst-class:: nag-rules-none nag-align-left
+---------+----------------------------------------------------+
|Level |Subspaces |
+=========+====================================================+
|:math:`1`|:math:`\left(1, 1\right)` |
+---------+----------------------------------------------------+
|:math:`2`|:math:`\left(2, 1\right)`, :math:`\left(1, 2\right)`|
+---------+----------------------------------------------------+
|:math:`3`|:math:`\left(2, 2\right)` |
+---------+----------------------------------------------------+
|:math:`4`|None |
+---------+----------------------------------------------------+
Hence one subspace is generated at level :math:`3`, and no subspaces are generated at level :math:`4`.
The level :math:`3` subspace :math:`\left(2, 2\right)` actually indicates that this is the full grid of level :math:`2`.
**Using md_sgq_multi_vec**
``md_sgq_multi_vec`` uses options, supplied in the option arrays :math:`\mathrm{comm}`\ ['iopts'] and :math:`\mathrm{comm}`\ ['opts'].
Before calling ``md_sgq_multi_vec``, these option arrays must be initialized using :meth:`opt_set`.
Once initialized, the required options may be set and queried using :meth:`opt_set` and :meth:`opt_get` respectively.
A complete list of the options available may be found in :ref:`Other Parameters <d01es-py2-py-other_params>`.
You may control the maximum level required, :math:`L`, using the option 'Maximum Level'.
Furthermore, you may control the first level at which the error comparison will take place using the option 'Minimum Level', allowing for the forced evaluation of a predetermined number of levels before the routine attempts to complete.
Completion is flagged when the error estimate is sufficiently small:
.. math::
\left\lvert \hat{F}_d^k-\hat{F}_d^{{k-1}}\right\rvert \leq \mathrm{max}\left(\epsilon_a, {\epsilon_r\times \hat{F}_d^k}\right)\text{,}
where :math:`\epsilon_a` and :math:`\epsilon_r` are the absolute and relative error tolerances, respectively, and :math:`k\leq L` is the highest level at which computation was performed.
The tolerances :math:`\epsilon_a` and :math:`\epsilon_r` can be controlled by setting the options 'Absolute Tolerance' and 'Relative Tolerance'.
Owing to the interlacing nature of the quadrature rules used herein, abscissae :math:`\mathbf{x}` required in lower level subspaces will also appear in higher-level subspaces.
This allows for calculations which will be repeated later to be stored and re-used.
However, this is naturally at the expense of memory.
It may also be at the expense of computational time, depending on the complexity of the integrands, as the lookup time for a given value is (at worst) :math:`\mathrm{O}\left(d\right)`.
Furthermore, as the sparse grid level increases, fewer subsequent levels will require values from the current level.
You may control the number of levels for which values are stored by setting the option 'Index Level'.
Two different sets of interlacing quadrature rules are selectable using the option 'Quadrature Rule': Gauss--Patterson and Clenshaw--Curtis.
Gauss--Patterson rules offer greater polynomial accuracy, whereas Clenshaw--Curtis rules are often effective for oscillatory integrands.
Clenshaw--Curtis rules require function values to be evaluated on the boundary of the hypercube, whereas Gauss--Patterson rules do not.
Both of these rules use precomputed weights, and as such there is an effective limit on :math:`m_q`; see the description of the option 'Quadrature Rule'.
The value of :math:`m_q` is returned by the queriable option 'Maximum Quadrature Level'.
``md_sgq_multi_vec`` also allows for non-isotropic sparse grids to be constructed.
This is done by appropriately setting the array :math:`\mathrm{maxdlv}`.
It should be emphasised that a non-isometric construction should only be used if the integrands behave in a suitable way.
For example, they may decay toward zero as the lesser dimensions approach their bounds of :math:`\Omega`.
It should also be noted that setting :math:`\mathrm{maxdlv}[k-1] = 1` will not reduce the dimension of the integrals, it will simply indicate that only one point in dimension :math:`k` should be used.
It is also advisable to approximate the integrals several times, once with an isometric construction of some level, and then with a non-isometric construction with higher levels in various dimensions.
If the difference between the solutions is significantly more than the returned error estimates, the assumptions of dimensional importance are probably incorrect.
The abscissae in each subspace are generally expressible in a sparse manner, because many of the elements of each abscissa will in fact be the centre point of the dimension, which is termed here the 'trivial' element.
In this function the trivial element is always returned as :math:`0.5` owing to the restriction to the :math:`\left[0, 1\right]` hypercube.
As such, the function :math:`\mathrm{f}` returns the abscissae in Compressed Column Storage (CCS) format (see `the F11 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11intro.html>`__).
This has particular advantages when using accelerator hardware to evaluate the required functions, as much less data must be forwarded.
It also, potentially, allows for calculations to be computed faster, as any sub-calculations dependent upon the trivial value may be potentially re-used.
.. _d01es-py2-py-references:
**References**
Caflisch, R E, Morokoff, W and Owen, A B, 1997, `Valuation of mortgage backed securities using Brownian bridges to reduce effective dimension`, Journal of Computational Finance (1), 27--46
Gerstner, T and Griebel, M, 1998, `Numerical integration using sparse grids`, Numerical Algorithms (18), 209--232
Smolyak, S A, 1963, `Quadrature and interpolation formulas for tensor products of certain classes of functions`, Dokl. Akad. Nauk SSSR (4), 240--243
"""
raise NotImplementedError
[docs]def md_gauss(nptvec, weight, abscis, f, data=None):
r"""
``md_gauss`` computes an estimate of a multidimensional integral (from :math:`1` to :math:`20` dimensions), given the analytic form of the integrand and suitable Gaussian weights and abscissae.
.. _d01fb-py2-py-doc:
For full information please refer to the NAG Library document for d01fb
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01fbf.html
.. _d01fb-py2-py-parameters:
**Parameters**
**nptvec** : int, array-like, shape :math:`\left(\textit{ndim}\right)`
:math:`\mathrm{nptvec}[\textit{j}-1]` must specify the number of points in the :math:`\textit{j}`\ th dimension of the summation, for :math:`\textit{j} = 1,2,\ldots,n`.
**weight** : float, array-like, shape :math:`\left(\textit{lwa}\right)`
Must contain in succession the weights for the various dimensions, i.e., :math:`\mathrm{weight}[k-1]` contains the :math:`i`\ th weight for the :math:`j`\ th dimension, with
.. math::
k = \mathrm{nptvec}[0]+\mathrm{nptvec}[1] + \cdots +\mathrm{nptvec}[j-2]+i\text{.}
**abscis** : float, array-like, shape :math:`\left(\textit{lwa}\right)`
Must contain in succession the abscissae for the various dimensions, i.e., :math:`\mathrm{abscis}[k-1]` contains the :math:`i`\ th abscissa for the :math:`j`\ th dimension, with
.. math::
k = \mathrm{nptvec}[0]+\mathrm{nptvec}[1] + \cdots +\mathrm{nptvec}[j-2]+i\text{.}
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand at a given point.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The coordinates of the point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`f\left(x\right)` evaluated at :math:`\mathrm{x}`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**mdint** : float
The estimate of the integral.
.. _d01fb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{lwa}` is too small. :math:`\textit{lwa} = \langle\mathit{\boldsymbol{value}}\rangle`. Minimum possible dimension: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ndim}\leq 20`.
(`errno` :math:`1`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ndim}\geq 1`.
.. _d01fb-py2-py-notes:
**Notes**
``md_gauss`` approximates a multidimensional integral by evaluating the summation
.. math::
\sum_{{i_1 = 1}}^{l_1}w_{{1,i_1}}\sum_{{i_2 = 1}}^{l_2}w_{{2,i_2}} \cdots \sum_{{i_n = 1}}^{l_n}w_{{n,i_n}}f\left(x_{{1,i_1}}, x_{{2,i_2}}, \ldots, x_{{n,i_n}}\right)
given the weights :math:`w_{{j,i_j}}` and abscissae :math:`x_{{j,i_j}}` for a multidimensional product integration rule (see Davis and Rabinowitz (1975)).
The number of dimensions may be anything from :math:`1` to :math:`20`.
The weights and abscissae for each dimension must have been placed in successive segments of the arrays :math:`\mathrm{weight}` and :math:`\mathrm{abscis}`; for example, by calling :meth:`dim1_gauss_wres` or :meth:`dim1_gauss_wgen` once for each dimension using a quadrature formula and number of abscissae appropriate to the range of each :math:`x_j` and to the functional dependence of :math:`f` on :math:`x_j`.
If normal weights are used, the summation will approximate the integral
.. math::
\int w_1\left(x_1\right)\int w_2\left(x_2\right) \cdots \int w_n\left(x_n\right)f\left(x_1, x_2, \ldots, x_n\right){dx_n} \cdots {dx_2}dx_1
where :math:`w_j\left(x\right)` is the weight function associated with the quadrature formula chosen for the :math:`j`\ th dimension; while if adjusted weights are used, the summation will approximate the integral
.. math::
\int \int \cdots \int f\left(x_1, x_2, \ldots, x_n\right){dx_n} \cdots {dx_2}dx_1\text{.}
You must supply a function to evaluate
.. math::
f\left(x_1, x_2, \ldots, x_n\right)
at any values of :math:`x_1,x_2,\ldots,x_n` within the range of integration.
.. _d01fb-py2-py-references:
**References**
Davis, P J and Rabinowitz, P, 1975, `Methods of Numerical Integration`, Academic Press
"""
raise NotImplementedError
[docs]def md_adapt(a, b, minpts, maxpts, f, eps, data=None):
r"""
``md_adapt`` attempts to evaluate a multidimensional integral (up to :math:`15` dimensions), with constant and finite limits, to a specified relative accuracy, using an adaptive subdivision strategy.
.. _d01fc-py2-py-doc:
For full information please refer to the NAG Library document for d01fc
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01fcf.html
.. _d01fc-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
The lower limits of integration, :math:`a_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
**b** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
The upper limits of integration, :math:`b_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
**minpts** : int
Must be set to the minimum number of integrand evaluations to be allowed.
**maxpts** : int
The maximum number of integrand evaluations to be allowed.
**f** : callable retval = f(z, data=None)
:math:`\mathrm{f}` must return the value of the integrand at a given point.
**Parameters**
**z** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The coordinates of the point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of the integrand :math:`f` at the given point.
**eps** : float
The relative error acceptable to you. When the solution is zero or very small relative accuracy may not be achievable but you may still set :math:`\mathrm{eps}` to a reasonable value and check for the error exit :math:`\mathrm{errno}` = 2.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**minpts** : int
Contains the actual number of integrand evaluations used by ``md_adapt``.
**acc** : float
The estimated relative error in :math:`\mathrm{finval}`.
**finval** : float
The best estimate obtained for the integral.
.. _d01fc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{maxpts}` is too small. :math:`\mathrm{maxpts} = \langle\mathit{\boldsymbol{value}}\rangle`. Minimum possible dimension: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{eps} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{eps} > 0.0`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{minpts} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{maxpts} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{minpts}\leq \mathrm{maxpts}`.
(`errno` :math:`1`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ndim}\leq 15`.
(`errno` :math:`1`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ndim}\geq 2`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
:math:`\mathrm{maxpts}` too small to obtain requested accuracy :math:`\mathrm{eps}`: :math:`\mathrm{maxpts} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{eps} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
:math:`\textit{lenwrk}` was too small to complete computation. :math:`\mathrm{finval}` and :math:`\mathrm{acc}` contain estimates of integral and relative error, but :math:`\mathrm{acc}` is greater than :math:`\mathrm{eps}`.
.. _d01fc-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``md_adapt`` returns an estimate of a multidimensional integral over a hyper-rectangle (i.e., with constant limits), and also an estimate of the relative error.
You set the relative accuracy required, return values for the integrand via a function argument :math:`\mathrm{f}`, and also set the minimum and maximum acceptable number of calls to :math:`\mathrm{f}` (in :math:`\mathrm{minpts}` and :math:`\mathrm{maxpts}`).
The function operates by repeated subdivision of the hyper-rectangular region into smaller hyper-rectangles.
In each subregion, the integral is estimated using a seventh-degree rule, and an error estimate is obtained by comparison with a fifth-degree rule which uses a subset of the same points.
The fourth differences of the integrand along each coordinate axis are evaluated, and the subregion is marked for possible future subdivision in half along that coordinate axis which has the largest absolute fourth difference.
If the estimated errors, totalled over the subregions, exceed the requested relative error (or if fewer than :math:`\mathrm{minpts}` calls to :math:`\mathrm{f}` have been made), further subdivision is necessary, and is performed on the subregion with the largest estimated error, that subregion being halved along the appropriate coordinate axis.
The function will fail if the requested relative error level has not been attained by the time :math:`\mathrm{maxpts}` calls to :math:`\mathrm{f}` have been made; or, if the amount :math:`\textit{lenwrk}` of working storage is insufficient. A formula for the recommended value of :math:`\textit{lenwrk}` is given in :ref:`Parameters <d01fc-py2-py-parameters>`. If a smaller value is used, and is exhausted in the course of execution, the function switches to a less efficient mode of operation; only if this mode also breaks down is insufficient storage reported.
``md_adapt`` is based on the HALF function developed by van Dooren and de Ridder (1976).
It uses a different basic rule, described in Genz and Malik (1980).
.. _d01fc-py2-py-references:
**References**
Genz, A C and Malik, A A, 1980, `An adaptive algorithm for numerical integration over an N-dimensional rectangular region`, J. Comput. Appl. Math. (6), 295--302
van Dooren, P and de Ridder, L, 1976, `An adaptive algorithm for numerical integration over an N-dimensional cube`, J. Comput. Appl. Math. (2), 207--217
"""
raise NotImplementedError
[docs]def md_sphere(ndim, f, sigma, limit, region=None, r0=0.8, u=1.5, data=None):
r"""
``md_sphere`` calculates an approximation to a definite integral in up to :math:`30` dimensions, using the method of Sag and Szekeres (see Sag and Szekeres (1964)).
The region of integration is an :math:`n`-sphere, or by built-in transformation via the unit :math:`n`-cube, any product region.
.. _d01fd-py2-py-doc:
For full information please refer to the NAG Library document for d01fd
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01fdf.html
.. _d01fd-py2-py-parameters:
**Parameters**
**ndim** : int
:math:`n`, the number of dimensions of the integral.
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a given point.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The coordinates of the point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`f\left(x\right)` evaluated at :math:`\mathrm{x}`.
**sigma** : float
Indicates the region of integration.
:math:`\mathrm{sigma}\geq 0.0`
The integration is carried out over the :math:`n`-sphere of radius :math:`\mathrm{sigma}`, centred at the origin.
:math:`\mathrm{sigma} < 0.0`
The integration is carried out over the product region described by :math:`\mathrm{region}`.
**limit** : int
The approximate maximum number of integrand evaluations to be used.
**region** : None or callable (c, d) = region(x, j, data=None), optional
Note: if this argument is **None** then a NAG-supplied facility will be used.
If :math:`\mathrm{sigma} < 0.0`, :math:`\mathrm{region}` must evaluate the limits of integration in any dimension.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
:math:`\mathrm{x}[0],\ldots,\mathrm{x}[j-2]` contain the current values of the first :math:`\left(j-1\right)` variables, which may be used if necessary in calculating :math:`c_j` and :math:`d_j`.
**j** : int
The index :math:`j` for which the limits of the range of integration are required.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**c** : float
The lower limit :math:`c_j` of the range of :math:`x_j`.
**d** : float
The upper limit :math:`d_j` of the range of :math:`x_j`.
**r0** : float, optional
The cut-off radius on the unit :math:`n`-sphere, which may be regarded as an adjustable parameter of the method.
**u** : float, optional
Must specify an adjustable parameter of the transformation to the unit :math:`n`-sphere.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**ncalls** : int
The actual number of integrand evaluations used. (See also `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01fdf.html#fcomments>`__.)
.. _d01fd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ndim}\leq 30`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ndim}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{limit} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{limit}\geq 100`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{r0} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{r0} < 1.0`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{r0} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{r0} > 0.0`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{u} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{u} > 0.0`.
.. _d01fd-py2-py-notes:
**Notes**
``md_sphere`` calculates an approximation to
.. math::
\int_{{n\text{-sphere of radius }\sigma }}f\left(x_1, x_2, \ldots, x_n\right){dx_1}{dx_2} \cdots {dx_n}
or, more generally,
.. math::
\int_{c_1}^{d_1}{dx_1} \cdots \int_{c_n}^{d_n}{dx_n}f\left(x_1, \ldots, x_n\right)
where each :math:`c_i` and :math:`d_i` may be functions of :math:`x_j` :math:`\left(j < i\right)`.
The function uses the method of Sag and Szekeres (1964), which exploits a property of the shifted :math:`p`-point trapezoidal rule, namely, that it integrates exactly all polynomials of degree :math:`\text{} < p` (see Krylov (1962)).
An attempt is made to induce periodicity in the integrand by making a parameterised transformation to the unit :math:`n`-sphere.
The Jacobian of the transformation and all its direct derivatives vanish rapidly towards the surface of the unit :math:`n`-sphere, so that, except for functions which have strong singularities on the boundary, the resulting integrand will be pseudo-periodic.
In addition, the variation in the integrand can be considerably reduced, causing the trapezoidal rule to perform well.
Integrals of the form `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01fdf.html#eqn1>`__ are transformed to the unit :math:`n`-sphere by the change of variables:
.. math::
x_i = y_i\frac{\sigma }{r}\tanh\left(\frac{{ur}}{{1-r^2}}\right)
where :math:`r^2 = \sum_{{i = 1}}^ny_i^2` and :math:`u` is an adjustable parameter.
Integrals of the form `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01fdf.html#eqn2>`__ are first of all transformed to the :math:`n`-cube :math:`\left[-1, 1\right]^n` by a linear change of variables
.. math::
x_i = \left(\left(d_i+c_i\right)+\left(d_i-c_i\right)y_i\right)/2
and then to the unit sphere by a further change of variables
.. math::
y_i = \tanh\left(\frac{{uz_i}}{{1-r}}\right)
where :math:`r^2 = \sum_{{i = 1}}^nz_i^2` and :math:`u` is again an adjustable parameter.
The parameter :math:`u` in these transformations determines how the transformed integrand is distributed between the origin and the surface of the unit :math:`n`-sphere.
A typical value of :math:`u` is :math:`1.5`.
For larger :math:`u`, the integrand is concentrated toward the centre of the unit :math:`n`-sphere, while for smaller :math:`u` it is concentrated toward the perimeter.
In performing the integration over the unit :math:`n`-sphere by the trapezoidal rule, a displaced equidistant grid of size :math:`h` is constructed.
The points of the mesh lie on concentric layers of radius
.. math::
r_i = \frac{h}{4}\sqrt{n+8\left(i-1\right)}\text{, }\quad i = 1,2,3,\ldots \text{.}
The function requires you to specify an approximate maximum number of points to be used, and then computes the largest number of whole layers to be used, subject to an upper limit of :math:`400` layers.
In practice, the rapidly-decreasing Jacobian makes it unnecessary to include the whole unit :math:`n`-sphere and the integration region is limited by a user-specified cut-off radius :math:`r_0 < 1`.
The grid-spacing :math:`h` is determined by :math:`r_0` and the number of layers to be used.
A typical value of :math:`r_0` is :math:`0.8`.
Some experimentation may be required with the choice of :math:`r_0` (which determines how much of the unit :math:`n`-sphere is included) and :math:`u` (which determines how the transformed integrand is distributed between the origin and surface of the unit :math:`n`-sphere), to obtain best results for particular families of integrals.
This matter is discussed further in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01fdf.html#fcomments>`__.
.. _d01fd-py2-py-references:
**References**
Krylov, V I, 1962, `Approximate Calculation of Integrals`, (trans A H Stroud), Macmillan
Sag, T W and Szekeres, G, 1964, `Numerical evaluation of high-dimensional integrals`, Math. Comput. (18), 245--253
"""
raise NotImplementedError
[docs]def dim1_data(x, y):
r"""
``dim1_data`` integrates a function which is specified numerically at four or more points, over the whole of its specified range, using third-order finite difference formulae with error estimates, according to a method due to Gill and Miller (1972).
.. _d01ga-py2-py-doc:
For full information please refer to the NAG Library document for d01ga
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gaf.html
.. _d01ga-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
The values of the independent variable, i.e., the :math:`x_1,x_2,\ldots,x_n`.
**y** : float, array-like, shape :math:`\left(n\right)`
The values of the dependent variable :math:`y_{\textit{i}}` at the points :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
**Returns**
**ans** : float
The estimated value of the integral.
**er** : float
An estimate of the uncertainty in :math:`\mathrm{ans}`.
.. _d01ga-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 4`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{x}[0] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{x}[1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[I-2] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: either :math:`\mathrm{x}[0] < \mathrm{x}[1] < \cdots < \mathrm{x}[n-1]` or :math:`\mathrm{x}[0] > \mathrm{x}[1] > \cdots > \mathrm{x}[n-1]`.
(`errno` :math:`3`)
On entry, :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{x}[I-2] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{x}[I-1]\neq \mathrm{x}[I-2]`.
.. _d01ga-py2-py-notes:
**Notes**
``dim1_data`` evaluates the definite integral
.. math::
I = \int_{x_1}^{x_n}y\left(x\right){dx}\text{,}
where the function :math:`y` is specified at the :math:`n`-points :math:`x_1,x_2,\ldots,x_n`, which should be all distinct, and in either ascending or descending order.
The integral between successive points is calculated by a four-point finite difference formula centred on the interval concerned, except in the case of the first and last intervals, where four-point forward and backward difference formulae respectively are employed.
If :math:`n` is less than :math:`4`, the function fails.
An approximation to the truncation error is integrated and added to the result.
It is also returned separately to give an estimate of the uncertainty in the result.
The method is due to Gill and Miller (1972).
.. _d01ga-py2-py-references:
**References**
Gill, P E and Miller, G F, 1972, `An algorithm for the integration of unequally spaced data`, Comput. J. (15), 80--83
"""
raise NotImplementedError
[docs]def md_mcarlo(a, b, mincls, maxcls, f, eps, wrkstr, finest, data=None):
r"""
``md_mcarlo`` returns an approximation to the integral of a function over a hyper-rectangular region, using a Monte Carlo method.
An approximate relative error estimate is also returned.
This function is suitable for low accuracy work.
.. _d01gb-py2-py-doc:
For full information please refer to the NAG Library document for d01gb
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gbf.html
.. _d01gb-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
The lower limits of integration, :math:`a_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
**b** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
The upper limits of integration, :math:`b_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
**mincls** : int
Must be set
either to the minimum number of integrand evaluations to be allowed, in which case :math:`\mathrm{mincls}\geq 0`;
or to a negative value. In this case, the function assumes that a previous call had been made with the same arguments :math:`\textit{ndim}`, :math:`\mathrm{a}` and :math:`\mathrm{b}` and with either the same integrand (in which case ``md_mcarlo`` continues calculation) or a similar integrand (in which case ``md_mcarlo`` begins the calculation with the subdivision used in the last iteration of the previous call). See also :math:`\mathrm{wrkstr}`.
**maxcls** : int
The maximum number of integrand evaluations to be allowed. In the continuation case this is the number of new integrand evaluations to be allowed. These counts do not include zero integrand values.
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand at a given point.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The coordinates of the point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of the integrand :math:`f` at the given point.
**eps** : float
The relative accuracy required.
**wrkstr** : float, array-like, shape :math:`\left(\textit{lenwrk}\right)`
If :math:`\mathrm{mincls} < 0`, :math:`\mathrm{wrkstr}` must be unchanged from the previous call of ``md_mcarlo`` -- except that for a new integrand :math:`\mathrm{wrkstr}[\textit{lenwrk}-1]` must be set to :math:`0.0`. See also :math:`\mathrm{mincls}`.
**finest** : float
Must be unchanged from a previous call to ``md_mcarlo``.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**mincls** : int
Contains the number of integrand evaluations actually used by ``md_mcarlo``.
**acc** : float
The estimated relative accuracy of :math:`\mathrm{finest}`.
**wrkstr** : float, ndarray, shape :math:`\left(\textit{lenwrk}\right)`
Contains information about the current sub-interval structure which could be used in later calls of ``md_mcarlo``. In particular, :math:`\mathrm{wrkstr}[j-1]` gives the number of sub-intervals used along the :math:`j`\ th coordinate axis.
**finest** : float
The best estimate obtained for the integral.
.. _d01gb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{eps} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{eps}\geq 0.0`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{maxcls} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{maxcls}\geq 4\times \left(\textit{ndim}+1\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{maxcls} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{mincls} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{maxcls} > \mathrm{mincls}`.
(`errno` :math:`1`)
On entry, :math:`\textit{lenwrk}` is too small. :math:`\textit{lenwrk} = \langle\mathit{\boldsymbol{value}}\rangle`. Minimum possible dimension: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ndim}\geq 1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
:math:`\mathrm{maxcls}` too small to obtain required accuracy :math:`\mathrm{eps}`. :math:`\mathrm{maxcls} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{eps} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _d01gb-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``md_mcarlo`` uses an adaptive Monte Carlo method based on the algorithm described in Lautrup (1971).
It is implemented for integrals of the form:
.. math::
\int_{a_1}^{{b_1}}\int_{a_2}^{{b_2}} \cdots \int_{a_n}^{{b_n}}f\left(x_1, x_2, \ldots, x_n\right){dx_n} \cdots {dx_2}dx_1\text{.}
Upon entry, unless :math:`\textit{lenwrk}` has been set to the minimum value :math:`10\times \textit{ndim}`, the function subdivides the integration region into a number of equal volume subregions.
Inside each subregion the integral and the variance are estimated by means of pseudorandom sampling.
All contributions are added together to produce an estimate for the whole integral and total variance.
The variance along each coordinate axis is determined and the function uses this information to increase the density and change the widths of the sub-intervals along each axis, so as to reduce the total variance.
The total number of subregions is then increased by a factor of two and the program recycles for another iteration.
The program stops when a desired accuracy has been reached or too many integral evaluations are needed for the next cycle.
.. _d01gb-py2-py-references:
**References**
Lautrup, B, 1971, `An adaptive multi-dimensional integration procedure`, Proc. 2nd Coll. Advanced Methods in Theoretical Physics, Marseille
"""
raise NotImplementedError
[docs]def md_numth(f, region, npts, vk, nrand, itrans=0, data=None):
r"""
``md_numth`` calculates an approximation to a definite integral in up to :math:`20` dimensions, using the Korobov--Conroy number theoretic method.
.. _d01gc-py2-py-doc:
For full information please refer to the NAG Library document for d01gc
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gcf.html
.. _d01gc-py2-py-parameters:
**Parameters**
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a given point.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The coordinates of the point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`f\left(x\right)` evaluated at :math:`\mathrm{x}`.
**region** : callable (c, d) = region(x, j, data=None)
:math:`\mathrm{region}` must evaluate the limits of integration in any dimension.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
:math:`\mathrm{x}[0],\ldots,\mathrm{x}[j-2]` contain the current values of the first :math:`\left(j-1\right)` variables, which may be used if necessary in calculating :math:`c_j` and :math:`d_j`.
**j** : int
The index :math:`j` for which the limits of the range of integration are required.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**c** : float
The lower limit :math:`c_j` of the range of :math:`x_j`.
**d** : float
The upper limit :math:`d_j` of the range of :math:`x_j`.
**npts** : int
The Korobov rule to be used. There are two alternatives depending on the value of :math:`\mathrm{npts}`.
(i) :math:`1\leq \mathrm{npts}\leq 6`.
In this case one of six preset rules is chosen using :math:`2129`, :math:`5003`, :math:`10007`, :math:`20011`, :math:`40009` or :math:`80021` points depending on the respective value of :math:`\mathrm{npts}` being :math:`1`, :math:`2`, :math:`3`, :math:`4`, :math:`5` or :math:`6`.
(#) :math:`\mathrm{npts} > 6`.
:math:`\mathrm{npts}` is the number of actual points to be used with corresponding optimal coefficients supplied in the array :math:`\mathrm{vk}`.
**vk** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
If :math:`\mathrm{npts} > 6`, :math:`\mathrm{vk}` must contain the :math:`n` optimal coefficients (which may be calculated using :meth:`md_numth_coeff_prime` or :meth:`md_numth_coeff_2prime`).
If :math:`\mathrm{npts}\leq 6`, :math:`\mathrm{vk}` need not be set.
**nrand** : int
The number of random samples to be generated in the error estimation (generally a small value, say :math:`3` to :math:`5`, is sufficient). The total number of integrand evaluations will be :math:`\mathrm{nrand}\times \mathrm{npts}`.
**itrans** : int, optional
Indicates whether the periodising transformation is to be used.
:math:`\mathrm{itrans} = \texttt{'0'}`
The transformation is to be used.
:math:`\mathrm{itrans} \neq \texttt{'0'}`
The transformation is to be suppressed (to cover cases where the integrand may already be periodic or where you want to specify a particular transformation in the definition of :math:`\mathrm{f}`).
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**vk** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
If :math:`\mathrm{npts} > 6`, :math:`\mathrm{vk}` is unchanged.
If :math:`\mathrm{npts}\leq 6`, :math:`\mathrm{vk}` contains the :math:`n` optimal coefficients used by the preset rule.
**res** : float
The approximation to the integral :math:`I`.
**err** : float
The standard error as computed from :math:`\mathrm{nrand}` sample values. If :math:`\mathrm{nrand} = 1`, :math:`\mathrm{err}` contains zero.
.. _d01gc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`1\leq \textit{ndim}\leq 20`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{npts}\geq 1`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{nrand} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nrand}\geq 1`.
.. _d01gc-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``md_numth`` calculates an approximation to the integral
.. math::
I = \int_{c_1}^{d_1}{dx_1},\ldots,\int_{c_n}^{d_n}{dx_n}\quad \text{ }\quad f\left(x_1, x_2, \ldots, x_n\right)
using the Korobov--Conroy number theoretic method (see Korobov (1957), Korobov (1963) and Conroy (1967)).
The region of integration defined in `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gcf.html#eqn1>`__ is such that generally :math:`c_i` and :math:`d_i` may be functions of :math:`x_1,x_2,\ldots,x_{{i-1}}`, for :math:`i = 2,3,\ldots,n`, with :math:`c_1` and :math:`d_1` constants.
The integral is first of all transformed to an integral over the :math:`n`-cube :math:`\left[0, 1\right]^n` by the change of variables
.. math::
x_i = c_i+\left(d_i-c_i\right)y_i\text{, }\quad i = 1,2,\ldots,n\text{.}
The method then uses as its basis the number theoretic formula for the :math:`n`-cube, :math:`\left[0, 1\right]^n`:
.. math::
\int_0^1{dx_1} \cdots \int_0^1{dx_n}g\left(x_1, x_2, \ldots, x_n\right) = \frac{1}{p}\sum_{{k = 1}}^pg\left(\left\{k\frac{a_1}{p}\right\}, \ldots, \left\{k\frac{a_n}{p}\right\}\right)-E
where :math:`\left\{x\right\}` denotes the fractional part of :math:`x`, :math:`a_1,a_2,\ldots,a_n` are the so-called optimal coefficients, :math:`E` is the error, and :math:`p` is a prime integer. (It is strictly only necessary that :math:`p` be relatively prime to all :math:`a_1,a_2,\ldots,a_n` and is in fact chosen to be even for some cases in Conroy (1967).) The method makes use of properties of the Fourier expansion of :math:`g\left(x_1, x_2, \ldots, x_n\right)` which is assumed to have some degree of periodicity.
Depending on the choice of :math:`a_1,a_2,\ldots,a_n` the contributions from certain groups of Fourier coefficients are eliminated from the error, :math:`E`.
Korobov shows that :math:`a_1,a_2,\ldots,a_n` can be chosen so that the error satisfies
.. math::
E\leq CKp^{{-\alpha }}\mathrm{ln}^{{\alpha \beta }}\left(p\right)
where :math:`\alpha` and :math:`C` are real numbers depending on the convergence rate of the Fourier series, :math:`\beta` is a constant depending on :math:`n`, and :math:`K` is a constant depending on :math:`\alpha` and :math:`n`.
There are a number of procedures for calculating these optimal coefficients.
Korobov imposes the constraint that
.. math::
a_1 = 1\quad \text{ and }\quad a_i = a^{{i-1}}\hspace{1em}\left(\mathrm{mod}\hspace{.2em}p\right)
and gives a procedure for calculating the argument, :math:`a`, to satisfy the optimal conditions.
In this function the periodisation is achieved by the simple transformation
.. math::
x_i = y_i^2\left(3-2y_i\right)\text{, }\quad i = 1,2,\ldots,n\text{.}
More sophisticated periodisation procedures are available but in practice the degree of periodisation does not appear to be a critical requirement of the method.
An easily calculable error estimate is not available apart from repetition with an increasing sequence of values of :math:`p` which can yield erratic results.
The difficulties have been studied by Cranley and Patterson (1976) who have proposed a Monte Carlo error estimate arising from converting `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gcf.html#eqn2>`__ into a stochastic integration rule by the inclusion of a random origin shift which leaves the form of the error `(3) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gcf.html#eqn3>`__ unchanged; i.e., in the formula `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gcf.html#eqn2>`__, :math:`\left\{k\frac{a_i}{p}\right\}` is replaced by :math:`\left\{\alpha_i+k\frac{a_i}{p}\right\}`, for :math:`i = 1,2,\ldots,n`, where each :math:`\alpha_i`, is uniformly distributed over :math:`\left[0, 1\right]`.
Computing the integral for each of a sequence of random vectors :math:`\alpha` allows a 'standard error' to be estimated.
This function provides built-in sets of optimal coefficients, corresponding to six different values of :math:`p`.
Alternatively, the optimal coefficients may be supplied by you. Functions :meth:`md_numth_coeff_prime` and :meth:`md_numth_coeff_2prime` compute the optimal coefficients for the cases where :math:`p` is a prime number or :math:`p` is a product of two primes, respectively.
.. _d01gc-py2-py-references:
**References**
Conroy, H, 1967, `Molecular Shroedinger equation VIII. A new method for evaluting multi-dimensional integrals`, J. Chem. Phys. (47), 5307--5318
Cranley, R and Patterson, T N L, 1976, `Randomisation of number theoretic methods for mulitple integration`, SIAM J. Numer. Anal. (13), 904--914
Korobov, N M, 1957, `The approximate calculation of multiple integrals using number theoretic methods`, Dokl. Acad. Nauk SSSR (115), 1062--1065
Korobov, N M, 1963, `Number Theoretic Methods in Approximate Analysis`, Fizmatgiz, Moscow
"""
raise NotImplementedError
[docs]def md_numth_vec(vecfun, vecreg, npts, vk, nrand, itrans=0, data=None):
r"""
``md_numth_vec`` calculates an approximation to a definite integral in up to :math:`20` dimensions, using the Korobov--Conroy number theoretic method. This function is designed to be particularly efficient on vector processors.
.. _d01gd-py2-py-doc:
For full information please refer to the NAG Library document for d01gd
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gdf.html
.. _d01gd-py2-py-parameters:
**Parameters**
**vecfun** : callable fv = vecfun(x, data=None)
:math:`\mathrm{vecfun}` must evaluate the integrand at a specified set of points.
**Parameters**
**x** : float, ndarray, shape :math:`\left(m, \textit{ndim}\right)`
The coordinates of the :math:`m` points at which the integrand must be evaluated. :math:`\mathrm{x}[i-1,j-1]` contains the :math:`j`\ th coordinate of the :math:`i`\ th point.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fv** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{fv}[\textit{i}-1]` must contain the value of the integrand of the :math:`\textit{i}`\ th point, i.e., :math:`\mathrm{fv}[\textit{i}-1] = f\left({\mathrm{x}[\textit{i}-1,0]}, {\mathrm{x}[\textit{i}-1,1]}, \ldots, {\mathrm{x}[\textit{i}-1,\textit{ndim}-1]}\right)`, for :math:`\textit{i} = 1,2,\ldots,m`.
**vecreg** : callable (c, d) = vecreg(x, j, data=None)
:math:`\mathrm{vecreg}` must evaluate the limits of integration in any dimension for a set of points.
**Parameters**
**x** : float, ndarray, shape :math:`\left(m, \textit{ndim}\right)`
For :math:`i = 1,2,\ldots,m`, :math:`\mathrm{x}[i-1,0]`, :math:`\mathrm{x}[i-1,1],\ldots,\mathrm{x}[i-1,j-2]` contain the current values of the first :math:`\left(j-1\right)` coordinates of the :math:`i`\ th point, which may be used if necessary in calculating the :math:`m` values of :math:`c_j` and :math:`d_j`.
**j** : int
The index :math:`j` for which the limits of the range of integration are required.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**c** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{c}[\textit{i}-1]` must be set to the lower limit of the range for :math:`\mathrm{x}[\textit{i}-1,j-1]`, for :math:`\textit{i} = 1,2,\ldots,m`.
**d** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{d}[\textit{i}-1]` must be set to the upper limit of the range for :math:`\mathrm{x}[\textit{i}-1,j-1]`, for :math:`\textit{i} = 1,2,\ldots,m`.
**npts** : int
The Korobov rule to be used. There are two alternatives depending on the value of :math:`\mathrm{npts}`.
(i) :math:`1\leq \mathrm{npts}\leq 6`.
In this case one of six preset rules is chosen using :math:`2129`, :math:`5003`, :math:`10007`, :math:`20011`, :math:`40009` or :math:`80021` points depending on the respective value of :math:`\mathrm{npts}` being :math:`1`, :math:`2`, :math:`3`, :math:`4`, :math:`5` or :math:`6`.
(#) :math:`\mathrm{npts} > 6`.
:math:`\mathrm{npts}` is the number of actual points to be used with corresponding optimal coefficients supplied in the array :math:`\mathrm{vk}`.
**vk** : float, array-like, shape :math:`\left(\textit{ndim}\right)`
If :math:`\mathrm{npts} > 6`, :math:`\mathrm{vk}` must contain the :math:`n` optimal coefficients (which may be calculated using :meth:`md_numth_coeff_prime` or :meth:`md_numth_coeff_2prime`).
If :math:`\mathrm{npts}\leq 6`, :math:`\mathrm{vk}` need not be set.
**nrand** : int
The number of random samples to be generated (generally a small value, say :math:`3` to :math:`5`, is sufficient). The estimate, :math:`\mathrm{res}`, of the value of the integral returned by the function is then the average of :math:`\mathrm{nrand}` calculations with different random origin shifts. If :math:`\mathrm{npts} > 6`, the total number of integrand evaluations will be :math:`\mathrm{nrand}\times \mathrm{npts}`. If :math:`1\leq \mathrm{npts}\leq 6`, the number of integrand evaluations will be :math:`\mathrm{nrand}\times p`, where :math:`p` is the number of points corresponding to the six preset rules. For reasons of efficiency, these values are calculated a number at a time in :math:`\mathrm{vecfun}`.
**itrans** : int, optional
Indicates whether the periodising transformation is to be used.
:math:`\mathrm{itrans} = 0`
The transformation is to be used.
:math:`\mathrm{itrans} = 1`
The transformation is to be suppressed (to cover cases where the integrand may already be periodic or where you want to specify a particular transformation in the definition of :math:`\mathrm{vecfun}`).
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**vk** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
If :math:`\mathrm{npts} > 6`, :math:`\mathrm{vk}` is unchanged.
If :math:`\mathrm{npts}\leq 6`, :math:`\mathrm{vk}` contains the :math:`n` optimal coefficients used by the preset rule.
**res** : float
The approximation to the integral :math:`I`.
**err** : float
The standard error as computed from :math:`\mathrm{nrand}` sample values. If :math:`\mathrm{nrand} = 1`, :math:`\mathrm{err}` contains zero.
.. _d01gd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`1\leq \textit{ndim}\leq 20`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{npts}\geq 1`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{nrand} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nrand}\geq 1`.
.. _d01gd-py2-py-notes:
**Notes**
``md_numth_vec`` calculates an approximation to the integral
.. math::
I = \int_{c_1}^{d_1} \cdots \int_{c_n}^{d_n}f\left(x_1, \ldots, x_n\right){dx_n}\ldots {dx_1}
using the Korobov--Conroy number theoretic method (see Korobov (1957), Korobov (1963) and Conroy (1967)).
The region of integration defined in `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gdf.html#eqn1>`__ is such that generally :math:`c_i` and :math:`d_i` may be functions of :math:`x_1,x_2,\ldots,x_{{i-1}}`, for :math:`i = 2,3,\ldots,n`, with :math:`c_1` and :math:`d_1` constants.
The integral is first of all transformed to an integral over the :math:`n`-cube :math:`\left[0, 1\right]^n` by the change of variables
.. math::
x_i = c_i+\left(d_i-c_i\right)y_i\text{, }\quad i = 1,2,\ldots,n\text{.}
The method then uses as its basis the number theoretic formula for the :math:`n`-cube, :math:`\left[0, 1\right]^n`:
.. math::
\int_0^1 \cdots \int_0^1g\left(x_1, \ldots, x_n\right){dx_n} \cdots {dx_1} = \frac{1}{p}\sum_{{k = 1}}^pg\left(\left\{k\frac{a_1}{p}\right\}, \ldots, \left\{k\frac{a_n}{p}\right\}\right)-E
where :math:`\left\{x\right\}` denotes the fractional part of :math:`x`, :math:`a_1,\ldots,a_n` are the so-called optimal coefficients, :math:`E` is the error, and :math:`p` is a prime integer. (It is strictly only necessary that :math:`p` be relatively prime to all :math:`a_1,\ldots,a_n` and is in fact chosen to be even for some cases in Conroy (1967).) The method makes use of properties of the Fourier expansion of :math:`g\left(x_1, \ldots, x_n\right)` which is assumed to have some degree of periodicity.
Depending on the choice of :math:`a_1,\ldots,a_n` the contributions from certain groups of Fourier coefficients are eliminated from the error, :math:`E`.
Korobov shows that :math:`a_1,\ldots,a_n` can be chosen so that the error satisfies
.. math::
E\leq CKp^{{-\alpha }}\mathrm{ln}^{{\alpha \beta }}\left(p\right)
where :math:`\alpha` and :math:`C` are real numbers depending on the convergence rate of the Fourier series, :math:`\beta` is a constant depending on :math:`n`, and :math:`K` is a constant depending on :math:`\alpha` and :math:`n`.
There are a number of procedures for calculating these optimal coefficients.
Korobov imposes the constraint that
.. math::
a_1 = 1\quad \text{ and }\quad a_i = a^{{i-1}}\left(\mathrm{mod}\text{ }p\right)
and gives a procedure for calculating the argument, :math:`a`, to satisfy the optimal conditions.
In this function the periodisation is achieved by the simple transformation
.. math::
x_i = y_i^2\left(3-2y_i\right)\text{, }\quad i = 1,2,\ldots,n\text{.}
More sophisticated periodisation procedures are available but in practice the degree of periodisation does not appear to be a critical requirement of the method.
An easily calculable error estimate is not available apart from repetition with an increasing sequence of values of :math:`p` which can yield erratic results.
The difficulties have been studied by Cranley and Patterson (1976) who have proposed a Monte Carlo error estimate arising from converting `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gdf.html#eqn2>`__ into a stochastic integration rule by the inclusion of a random origin shift which leaves the form of the error `(3) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gdf.html#eqn3>`__ unchanged; i.e., in the formula `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gdf.html#eqn2>`__, :math:`\left\{k\frac{a_i}{p}\right\}` is replaced by :math:`\left\{\alpha_i+k\frac{a_i}{p}\right\}`, for :math:`i = 1,2,\ldots,n`, where each :math:`\alpha_i`, is uniformly distributed over :math:`\left[0, 1\right]`.
Computing the integral for each of a sequence of random vectors :math:`\alpha` allows a 'standard error' to be estimated.
This function provides built-in sets of optimal coefficients, corresponding to six different values of :math:`p`.
Alternatively, the optimal coefficients may be supplied by you. Functions :meth:`md_numth_coeff_prime` and :meth:`md_numth_coeff_2prime` compute the optimal coefficients for the cases where :math:`p` is a prime number or :math:`p` is a product of two primes, respectively.
This function is designed to be particularly efficient on vector processors, although it is very important that you also code :math:`\mathrm{vecfun}` and :math:`\mathrm{vecreg}` efficiently.
.. _d01gd-py2-py-references:
**References**
Conroy, H, 1967, `Molecular Shroedinger equation VIII. A new method for evaluting multi-dimensional integrals`, J. Chem. Phys. (47), 5307--5318
Cranley, R and Patterson, T N L, 1976, `Randomisation of number theoretic methods for mulitple integration`, SIAM J. Numer. Anal. (13), 904--914
Korobov, N M, 1957, `The approximate calculation of multiple integrals using number theoretic methods`, Dokl. Acad. Nauk SSSR (115), 1062--1065
Korobov, N M, 1963, `Number Theoretic Methods in Approximate Analysis`, Fizmatgiz, Moscow
"""
raise NotImplementedError
[docs]def md_numth_coeff_prime(ndim, npts):
r"""
``md_numth_coeff_prime`` calculates the optimal coefficients for use by :meth:`md_numth` and :meth:`md_numth_vec`, for prime numbers of points.
.. _d01gy-py2-py-doc:
For full information please refer to the NAG Library document for d01gy
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gyf.html
.. _d01gy-py2-py-parameters:
**Parameters**
**ndim** : int
:math:`n`, the number of dimensions of the integral.
**npts** : int
:math:`p`, the number of points to be used.
**Returns**
**vk** : float, ndarray, shape :math:`\left(\mathrm{ndim}\right)`
The :math:`n` optimal coefficients.
.. _d01gy-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ndim}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{npts}\geq 5`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{npts}` must be a prime number.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`4`)
The machine precision is insufficient to perform the computation exactly. Try reducing :math:`\mathrm{npts}`: :math:`\mathrm{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _d01gy-py2-py-notes:
**Notes**
The Korobov (1963) procedure for calculating the optimal coefficients :math:`a_1,a_2,\ldots,a_n` for :math:`p`-point integration over the :math:`n`-cube :math:`\left[0, 1\right]^n` imposes the constraint that
.. math::
a_1 = 1\quad \text{ and }\quad a_i = a^{{i-1}}\left(\textit{ mod }p\right)\text{, }\quad i = 1,2,\ldots,n
where :math:`p` is a prime number and :math:`a` is an adjustable argument.
This argument is computed to minimize the error in the integral
.. math::
3^n\int_0^1{dx_1} \cdots \int_0^1{dx_n}\prod_{{i = 1}}^n\left(1-2x_i\right)^2\text{,}
when computed using the number theoretic rule, and the resulting coefficients can be shown to fit the Korobov definition of optimality.
The computation for large values of :math:`p` is extremely time consuming (the number of elementary operations varying as :math:`p^2`) and there is a practical upper limit to the number of points that can be used. Function :meth:`md_numth_coeff_2prime` is computationally more economical in this respect but the associated error is likely to be larger.
.. _d01gy-py2-py-references:
**References**
Korobov, N M, 1963, `Number Theoretic Methods in Approximate Analysis`, Fizmatgiz, Moscow
"""
raise NotImplementedError
[docs]def md_numth_coeff_2prime(ndim, np1, np2):
r"""
``md_numth_coeff_2prime`` calculates the optimal coefficients for use by :meth:`md_numth` and :meth:`md_numth_vec`, when the number of points is the product of two primes.
.. _d01gz-py2-py-doc:
For full information please refer to the NAG Library document for d01gz
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gzf.html
.. _d01gz-py2-py-parameters:
**Parameters**
**ndim** : int
:math:`n`, the number of dimensions of the integral.
**np1** : int
The larger prime factor :math:`p_1` of the number of points in the integration rule.
**np2** : int
The smaller prime factor :math:`p_2` of the number of points in the integration rule. For maximum efficiency, :math:`p_2^2` should be close to :math:`p_1`.
**Returns**
**vk** : float, ndarray, shape :math:`\left(\mathrm{ndim}\right)`
The :math:`n` optimal coefficients.
.. _d01gz-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ndim}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{np1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{np2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{np1} > \mathrm{np2}`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{np2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{np2}\geq 2`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{np1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{np1}\geq 5`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{np1}\times \mathrm{np2}` exceeds largest machine integer. :math:`\mathrm{np1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{np2} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{np1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{np1}` must be a prime number.
(`errno` :math:`5`)
On entry, :math:`\mathrm{np2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{np2}` must be a prime number.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`6`)
The machine precision is insufficient to perform the computation exactly. Try reducing :math:`\mathrm{np1}` or :math:`\mathrm{np2}`: :math:`\mathrm{np1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{np2} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _d01gz-py2-py-notes:
**Notes**
Korobov (1963) gives a procedure for calculating optimal coefficients for :math:`p`-point integration over the :math:`n`-cube :math:`\left[0, 1\right]^n`, when the number of points is
.. math::
p = p_1p_2
where :math:`p_1` and :math:`p_2` are distinct prime numbers.
The advantage of this procedure is that if :math:`p_1` is chosen to be the nearest prime integer to :math:`p_2^2`, then the number of elementary operations required to compute the rule is of the order of :math:`p^{{4/3}}` which grows less rapidly than the number of operations required by :meth:`md_numth_coeff_prime`.
The associated error is likely to be larger although it may be the only practical alternative for high values of :math:`p`.
.. _d01gz-py2-py-references:
**References**
Korobov, N M, 1963, `Number Theoretic Methods in Approximate Analysis`, Fizmatgiz, Moscow
"""
raise NotImplementedError
[docs]def md_sphere_bad(f, ndim, radius, epsa, epsr, icoord, method=0, data=None):
r"""
``md_sphere_bad`` attempts to evaluate an integral over an :math:`n`-dimensional sphere (:math:`n = 2`, :math:`3`, or :math:`4`), to a user-specified absolute or relative accuracy, by means of a modified Sag--Szekeres method.
The function can handle singularities on the surface or at the centre of the sphere, and returns an error estimate.
.. _d01ja-py2-py-doc:
For full information please refer to the NAG Library document for d01ja
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01jaf.html
.. _d01ja-py2-py-parameters:
**Parameters**
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a given point.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The coordinates of the point at which the integrand :math:`f` must be evaluated. These coordinates are given in Cartesian or spherical polar form according to the value of :math:`\mathrm{icoord}`.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of :math:`f\left(x\right)` evaluated at :math:`\mathrm{x}`.
**ndim** : int
:math:`n`, the dimension of the sphere.
**radius** : float
:math:`\alpha`, the radius of the sphere.
**epsa** : float
The requested absolute tolerance. If :math:`\mathrm{epsa} < 0.0`, its absolute value is used. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01jaf.html#accuracy>`__.
**epsr** : float
The requested relative tolerance.
:math:`\mathrm{epsr} < 0.0`
Its absolute value is used.
:math:`\mathrm{epsr} < 10\times \left(\text{machine precision}\right)`
The latter value is used as :math:`\mathrm{epsr}` by the function. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01jaf.html#accuracy>`__.
**icoord** : int
Must specify which kind of coordinates are used in :math:`\mathrm{f}`.
:math:`\mathrm{icoord} = 0`
Cartesian coordinates :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
:math:`\mathrm{icoord} = 1`
Spherical coordinates (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01jaf.html#fcomments2>`__): :math:`\mathrm{x}[0] = \rho`; :math:`\mathrm{x}[\textit{i}-1] = \theta_{{\textit{i}-1}}`, for :math:`\textit{i} = 2,3,\ldots,n`.
:math:`\mathrm{icoord} = 2`,
Special spherical polar coordinates (see `Machine Dependencies <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01jaf.html#fcomments3>`__), with the additional transformation :math:`\rho = \alpha -\lambda`: :math:`\mathrm{x}[0] = \lambda = \alpha -\rho`; :math:`\mathrm{x}[\textit{i}-1] = \theta_{{\textit{i}-1}}`, for :math:`\textit{i} = 2,3,\ldots,n`.
**method** : int, optional
Must specify the transformation to be used by the function. The choice depends on the behaviour of the integrand and on the required accuracy.
For well-behaved functions and functions with mild singularities on the surface of the sphere only:
:math:`\mathrm{method} = 1`
Low accuracy required.
:math:`\mathrm{method} = 2`
High accuracy required.
For functions with severe singularities on the surface of the sphere only:
:math:`\mathrm{method} = 3`
Low accuracy required.
:math:`\mathrm{method} = 4`
High accuracy required.
(in this case :math:`\mathrm{icoord}` must be set to :math:`\mathrm{icoord} = 2`, and the function defined in special spherical coordinates).
For functions with a singularity at the centre of the sphere (and possibly with singularities on the surface as well):
:math:`\mathrm{method} = 5`
Low accuracy required.
:math:`\mathrm{method} = 6`
High accuracy required.
:math:`\mathrm{method} = 0` can be used as a default value and is equivalent to:
:math:`\mathrm{method} = 1` if :math:`\mathrm{epsr} > 10^{-6}`, and
:math:`\mathrm{method} = 2` if :math:`\mathrm{epsr}\leq 10^{-6}`.
The distinction between low and high required accuracies, as mentioned above, depends also on the behaviour of the function.
Roughly one may assume the critical value of :math:`\mathrm{epsa}` and :math:`\mathrm{epsr}` to be :math:`10^{-6}`, but the critical value will be smaller for a well-behaved integrand and larger for an integrand with severe singularities.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**esterr** : float
An estimate of the modulus of the absolute error.
**nevals** : int
The number of function evaluations used.
.. _d01ja-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`4`)
On entry, :math:`\mathrm{radius} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{radius}\geq 0.0`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{method} = 4` and :math:`\mathrm{icoord} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: when :math:`\mathrm{method} = 4`, :math:`\mathrm{icoord} = 2`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{method} = 3` and :math:`\mathrm{icoord} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: when :math:`\mathrm{method} = 3`, :math:`\mathrm{icoord} = 2`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{icoord} = 2` and :math:`\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: when :math:`\mathrm{icoord} = 2`, :math:`\mathrm{method} = 3` or :math:`4`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ndim}\geq 2`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ndim}\leq 4`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The required accuracy could not be achieved.
(`errno` :math:`2`)
The required accuracy could not be achieved.
(`errno` :math:`3`)
The required accuracy could not be achieved.
If :math:`\mathrm{method} = 0`, :math:`1` or :math:`2`, setting :math:`\mathrm{method} = 3` or :math:`4` may help.
.. _d01ja-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``md_sphere_bad`` calculates an approximation to the :math:`n`-dimensional integral
.. math::
I = \int \cdots \int_SF\left(x_1, \ldots, x_n\right){dx_1} \cdots {dx_n}\text{, }\quad 2\leq n\leq 4\text{,}
where :math:`S` is the hypersphere
.. math::
\sqrt{\left(x_1^2 + \cdots +x_n^2\right)}\leq \alpha < \infty
(the integrand function may also be defined in spherical coordinates).
The algorithm is based on the Sag--Szekeres method (see Sag and Szekeres (1964)), applying the product trapezoidal formula after a suitable radial transformation.
An improved transformation technique is developed: depending on the behaviour of the function and on the required accuracy, different transformations can be used, some of which are 'double exponential', as defined by Takahasi and Mori (1974).
The resulting technique allows the function to deal with integrand singularities on the surface or at the centre of the sphere.
When the estimated error of the approximation with mesh size :math:`h` is larger than the tolerated error, the trapezoidal formula with mesh size :math:`h/2` is calculated.
A drawback of this method is the exponential growth of the number of function evaluations in the successive approximations (this number grows with a factor :math:`\text{}≈2^n`).
This introduces the restriction :math:`n\leq 4`.
Because the convergence rate of the successive approximations is normally better than linear, the error estimate is based on the linear extrapolation of the difference between the successive approximations (see Robinson and de Doncker (1981) and Roose and de Doncker (1981)).
For further details of the algorithm, see Roose and de Doncker (1981).
.. _d01ja-py2-py-references:
**References**
Robinson, I and de Doncker, E, 1981, `Automatic computation of improper integrals over a bounded or unbounded planar region`, Computing (27), 89--284
Roose, D and de Doncker, E, 1981, `Automatic integration over a sphere`, J. Comput. Appl. Math. (7), 203--224
Sag, T W and Szekeres, G, 1964, `Numerical evaluation of high-dimensional integrals`, Math. Comput. (18), 245--253
Takahasi, H and Mori, M, 1974, `Double Exponential Formulas for Numerical Integration` (9), Publ. RIMS, Kyoto University, 721--741
"""
raise NotImplementedError
[docs]def md_simplex(ndim, vert, f, minord, finvls, data=None):
r"""
``md_simplex`` returns a sequence of approximations to the integral of a function over a multidimensional simplex, together with an error estimate for the last approximation.
.. _d01pa-py2-py-doc:
For full information please refer to the NAG Library document for d01pa
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01paf.html
.. _d01pa-py2-py-parameters:
**Parameters**
**ndim** : int
:math:`n`, the number of dimensions of the integral.
**vert** : float, array-like, shape :math:`\left(\mathrm{ndim}+1, 2\times \left(\mathrm{ndim}+1\right)\right)`
:math:`\mathrm{vert}[\textit{i}-1,\textit{j}-1]` must be set to the :math:`\textit{j}`\ th component of the :math:`\textit{i}`\ th vertex for the simplex integration region, for :math:`\textit{j} = 1,2,\ldots,n`, for :math:`\textit{i} = 1,2,\ldots,n+1`. If :math:`\mathrm{minord} > 0`, :math:`\mathrm{vert}` must be unchanged since the previous call of ``md_simplex``.
**f** : callable retval = f(x, data=None)
:math:`\mathrm{f}` must return the value of the integrand at a given point.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{ndim}\right)`
The coordinates of the point at which the integrand :math:`f` must be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : float
The value of the integrand :math:`f` at the given point.
**minord** : int
Must specify the highest order of the approximations currently available in the array :math:`\mathrm{finvls}`.
:math:`\mathrm{minord} = 0`
Indicates an initial call.
:math:`\mathrm{minord} > 0`
Indicates that :math:`\mathrm{finvls}[0],\mathrm{finvls}[1],\ldots,\mathrm{finvls}[\mathrm{minord}-1]` have already been computed in a previous call of ``md_simplex``.
**finvls** : float, array-like, shape :math:`\left(\textit{maxord}\right)`
If :math:`\mathrm{minord} > 0`, :math:`\mathrm{finvls}[0],\mathrm{finvls}[1],\ldots,\mathrm{finvls}[\mathrm{minord}-1]` must contain approximations to the integral previously computed by ``md_simplex``.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**vert** : float, ndarray, shape :math:`\left(\mathrm{ndim}+1, 2\times \left(\mathrm{ndim}+1\right)\right)`
These values are unchanged. The rest of the array :math:`\mathrm{vert}` is used for workspace and contains information to be used if another call of ``md_simplex`` is made with :math:`\mathrm{minord} > 0`. In particular :math:`\mathrm{vert}[n,2n+1]` contains the volume of the simplex.
**minord** : int
:math:`\mathrm{minord} = \textit{maxord}`.
**finvls** : float, ndarray, shape :math:`\left(\textit{maxord}\right)`
Contains these values unchanged, and the newly computed values :math:`\mathrm{finvls}[\mathrm{minord}],\mathrm{finvls}[\mathrm{minord}+1],\ldots,\mathrm{finvls}[\textit{maxord}-1]`. :math:`\mathrm{finvls}[j-1]` is an approximation to the integral of polynomial degree :math:`2j-1`.
**esterr** : float
An absolute error estimate for :math:`\mathrm{finvls}[\textit{maxord}-1]`.
.. _d01pa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{maxord} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{minord} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{maxord} > \mathrm{minord}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{minord} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{minord}\geq 0`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ndim} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ndim}\geq 2`.
(`errno` :math:`2`)
The volume of the simplex integration region is too large or too small to be represented on the machine.
.. _d01pa-py2-py-notes:
**Notes**
``md_simplex`` computes a sequence of approximations :math:`\mathrm{finvls}[\textit{j}-1]`, for :math:`\textit{j} = \mathrm{minord}+1,\ldots,\textit{maxord}`, to an integral
.. math::
\int_Sf\left(x_1, x_2, \ldots, x_n\right){dx_1}dx_2 \cdots {dx_n}
where :math:`S` is an :math:`n`-dimensional simplex defined in terms of its :math:`n+1` vertices. :math:`\mathrm{finvls}[j-1]` is an approximation which will be exact (except for rounding errors) whenever the integrand is a polynomial of total degree :math:`2j-1` or less.
The type of method used has been described in Grundmann and Moller (1978), and is implemented in an extrapolated form using the theory from de Doncker (1979).
.. _d01pa-py2-py-references:
**References**
de Doncker, E, 1979, `New Euler--Maclaurin Expansions and their application to quadrature over the` :math:`s` `-dimensional simplex`, Math. Comput. (33), 1003--1018
Grundmann, A and Moller, H M, 1978, `Invariant integration formulas for the` :math:`n` `-simplex by combinatorial methods`, SIAM J. Numer. Anal. (15), 282--290
"""
raise NotImplementedError
[docs]def dim1_gen_vec_multi_rcomm(irevcm, a, b, needi, x, nx, fm, dinest, errest, comm):
r"""
``dim1_gen_vec_multi_rcomm`` is a general purpose adaptive integrator which calculates an approximation to a vector of definite integrals :math:`\mathbf{F}` over a finite range :math:`\left[a, b\right]`, given the vector of integrands :math:`\mathbf{f}\left(x\right)`.
.. math::
\mathbf{F} = \int_a^b\mathbf{f}\left(x\right)dx
If the same subdivisions of the range are equally good for functions :math:`f_1\left(x\right)` and :math:`f_2\left(x\right)`, because :math:`f_1\left(x\right)` and :math:`f_2\left(x\right)` have common areas of the range where they vary slowly and where they vary quickly, then we say that :math:`f_1\left(x\right)` and :math:`f_2\left(x\right)` are 'similar'. ``dim1_gen_vec_multi_rcomm`` is particularly effective for the integration of a vector of similar functions.
.. _d01ra-py2-py-doc:
For full information please refer to the NAG Library document for d01ra
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html
.. _d01ra-py2-py-parameters:
**Parameters**
**irevcm** : int
`On initial entry`: :math:`\mathrm{irevcm} = 1`.
:math:`\mathrm{irevcm} = 1`
Sets up data structures in :math:`\mathrm{comm}`\ ['icom'] and :math:`\mathrm{comm}`\ ['com'] and starts a new integration.
`On intermediate entry`: :math:`\mathrm{irevcm}` should normally be left unchanged. However, if :math:`\mathrm{irevcm}` is set to a negative value, ``dim1_gen_vec_multi_rcomm`` will terminate, (see :math:`\mathrm{irevcm} = 11` and :math:`\mathrm{irevcm} = 12` above).
**a** : float
:math:`a`, the lower bound of the domain.
**b** : float
:math:`b`, the upper bound of the domain.
If :math:`\left\lvert b-a\right\rvert < 10\epsilon`, where :math:`\epsilon` is the machine precision (see :meth:`machine.precision <naginterfaces.library.machine.precision>`), ``dim1_gen_vec_multi_rcomm`` will return :math:`\mathrm{dinest}[\textit{j}-1] = \mathrm{errest}[\textit{j}-1] = 0.0`, for :math:`\textit{j} = 1,2,\ldots,n_i`.
**needi** : int, ndarray, shape :math:`\left(\textit{ni}\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate exit`: :math:`\mathrm{needi}[j-1]` indicates what action must be taken for integral :math:`j = 1,2,\ldots n_i` (see :math:`\mathrm{irevcm}`).
:math:`\mathrm{needi}[j-1] = 0`
Do not provide :math:`f_j\left(x_i\right)`. Any provided values will be ignored.
:math:`\mathrm{needi}[j-1] = 1`
The values :math:`f_j\left(x_{\textit{i}}\right)` must be provided in :math:`\mathrm{fm}[j-1,\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
:math:`\mathrm{needi}[j-1] = 2`
The values :math:`f_j\left(x_i\right)` are not required, however the error estimate for integral :math:`j` is still above the requested tolerance. If you wish to provide values for the evaluation of integral :math:`j`, set :math:`\mathrm{needi}[j-1] = 1`, and supply :math:`f_j\left(x_{\textit{i}}\right)` in :math:`\mathrm{fm}[j-1,\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
:math:`\mathrm{needi}[j-1] = 3`
The error estimate for integral :math:`j` cannot be improved to below the requested tolerance directly, either because no more new splits may be performed due to exhaustion, or due to the detection of extremely bad integrand behaviour. However, providing the values :math:`f_j\left(x_i\right)` may still lead to some improvement, and may lead to an acceptable error estimate indirectly using Wynn's epsilon algorithm. If you wish to provide values for the evaluation of integral :math:`j`, set :math:`\mathrm{needi}[j-1] = 1`, and supply :math:`f_j\left(x_{\textit{i}}\right)` in :math:`\mathrm{fm}[j-1,\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
:math:`\mathrm{needi}[j-1] = 4`
The error estimate of integral :math:`j` is below the requested tolerance. If you believe this to be false, if for example the result in :math:`\mathrm{dinest}[j-1]` is greatly different to what you may expect, you may force the algorithm to re-evaluate this conclusion by including the evaluations of integrand :math:`j` at :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n_x`, and setting :math:`\mathrm{needi}[j-1] = 1`. Integral and error estimation will be performed again during the next iteration.
`On intermediate entry`: :math:`\mathrm{needi}[j-1]` may be used to indicate what action you have taken for integral :math:`j`.
:math:`\mathrm{needi}[j-1] = 1`
You have provided the values :math:`f_j\left(x_{\textit{i}}\right)` in :math:`\mathrm{fm}[j-1,\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
:math:`\mathrm{needi}[j-1] < 0`
You are abandoning the evaluation of integral :math:`j`. The current values of :math:`\mathrm{dinest}[j-1]` and :math:`\mathrm{errest}[j-1]` will be returned on final completion.
Otherwise you have not provided the value :math:`f_j\left(x_i\right)`.
`On final exit`: :math:`\mathrm{needi}[j-1]` indicates the final state of integral :math:`j`.
:math:`\mathrm{needi}[j-1] = 0`
The error estimate for :math:`F_j` is below the requested tolerance.
:math:`\mathrm{needi}[j-1] = 1`
The error estimate for :math:`F_j` is below the requested tolerance after extrapolation.
:math:`\mathrm{needi}[j-1] = 2`
The error estimate for :math:`F_j` is above the requested tolerance.
:math:`\mathrm{needi}[j-1] = 3`
The error estimate for :math:`F_j` is above the requested tolerance, and extremely bad behaviour of integral :math:`j` has been detected.
:math:`\mathrm{needi}[j-1] < 0`
You prohibited further evaluation of integral :math:`j`.
**x** : float, ndarray, shape :math:`\left(\textit{lenxrq}\right)`, modified in place
`On initial entry`: if :math:`\text{‘Primary Division Mode'} = \texttt{'AUTOMATIC'}`, :math:`\mathrm{x}` need not be set. This is the default behaviour.
If :math:`\text{‘Primary Division Mode'} = \texttt{'MANUAL'}`, :math:`\mathrm{x}` is used to supply a set of initial 'break-points' inside the domain of integration.
Specifically, :math:`\mathrm{x}[i-1]` must contain a break-point :math:`x_{\textit{i}}^0`, for :math:`\textit{i} = 1,2,\ldots,\left(s_{\textit{pri}}-1\right)`, where :math:`s_{\textit{pri}}` is the number of 'Primary Divisions'.
`On intermediate exit`: :math:`\mathrm{x}[\textit{i}-1]` is the abscissa :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n_x`, at which the appropriate integrals must be evaluated.
**nx** : int
`On initial entry`: need not be set.
`On intermediate entry`: must not be changed.
**fm** : float, array-like, shape :math:`\left(\textit{ldfmrq}, \textit{sdfmrq}\right)`
`On initial entry`: need not be set.
`On intermediate entry`: if indicated by :math:`\mathrm{needi}[j-1]` you must supply the values :math:`f_j\left(x_i\right)` in :math:`\mathrm{fm}[\textit{j}-1,\textit{i}-1]`, for :math:`\textit{j} = 1,2,\ldots,n_i`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
**dinest** : float, ndarray, shape :math:`\left(\textit{ni}\right)`, modified in place
:math:`\mathrm{dinest}[j-1]` contains the current estimate of the definite integral :math:`F_j`.
`On initial entry`: need not be set.
`On intermediate entry`: must not be altered.
`On exit`: contains the current estimates of the :math:`\textit{ni}` integrals. If :math:`\mathrm{irevcm} = 0`, this will be the final solution.
**errest** : float, ndarray, shape :math:`\left(\textit{ni}\right)`, modified in place
:math:`\mathrm{errest}[j-1]` contains the current error estimate of the definite integral :math:`F_j`.
`On initial entry`: need not be set.
`On intermediate entry`: must not be altered.
`On exit`: contains the current error estimates for the :math:`\textit{ni}` integrals. If :math:`\mathrm{irevcm} = 0`, :math:`\mathrm{errest}` contains the final error estimates of the :math:`\textit{ni}` integrals.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`opt_set`.
**Returns**
**irevcm** : int
`On intermediate exit`: :math:`\mathrm{irevcm} = 11` or :math:`12`.
:math:`\mathrm{irevcm}` requests the integrands :math:`f_j\left(x_i\right)` be evaluated for all required :math:`j \in 1,\ldots,n_i` as indicated by :math:`\mathrm{needi}`, and at all the points :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
Abscissae :math:`x_i` are provided in :math:`\mathrm{x}[i-1]` and :math:`f_j\left(x_i\right)` must be returned in :math:`\mathrm{fm}[j-1,i-1]`.
`During the initial solve phase`:
:math:`\mathrm{irevcm} = 11`
Function values are required to construct the initial estimates of the definite integrals.
If :math:`\mathrm{needi}[j-1] = 1`, :math:`f_j\left(x_i\right)` must be supplied in :math:`\mathrm{fm}[j-1,i-1]`.
This will be the case unless you have abandoned the evaluation of specific integrals on a previous call.
If :math:`\mathrm{needi}[j-1] = 0`, you have previously abandoned the evaluation of integral :math:`j`, and hence should not supply the value of :math:`f_j\left(x_i\right)`.
:math:`\mathrm{dinest}` and :math:`\mathrm{errest}` contain incomplete information during this phase.
As such you should not abandon the evaluation of any integrals during this phase unless you do not require their estimate.
If :math:`\mathrm{irevcm}` is set to a negative value during this phase, :math:`\mathrm{needi}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n_i`, will be set to this negative value and :math:`\mathrm{errno}` = -1 will be returned.
`During the adaptive solve phase`:
:math:`\mathrm{irevcm} = 12`
Function values are required to improve the estimates of the definite integrals.
If :math:`\mathrm{needi}[j-1] = 0`, any evaluation of :math:`f_j\left(x_i\right)` will be discarded, so there is no need to provide them.
If :math:`\mathrm{needi}[j-1] = 1`, :math:`f_j\left(x_i\right)` must be provided in :math:`\mathrm{fm}[j-1,i-1]`.
If :math:`\mathrm{needi}[j-1] = 2`, :math:`3` or :math:`4`, the current error estimate of integral :math:`j` does not require integrand :math:`j` to be evaluated and provided in :math:`\mathrm{fm}[j-1,i-1]`.
Should you choose to, integrand :math:`j` can be evaluated in which case :math:`\mathrm{needi}[j-1]` must be set to :math:`1`.
:math:`\mathrm{dinest}` and :math:`\mathrm{errest}` contain complete information during this phase.
If :math:`\mathrm{irevcm}` is set to a negative value during this phase :math:`\mathrm{errno}` = 1, 2 or 3 will be returned and the elements of :math:`\mathrm{needi}` will reflect the current state of the adaptive process.
`On final exit`: :math:`\mathrm{irevcm} = 0`.
:math:`\mathrm{irevcm} = 0`
Indicates the algorithm has completed.
**sid** : int
`For advanced users.`
`On intermediate exit`: :math:`\mathrm{sid}` identifies a specific set of abscissae, :math:`\mathbf{x}`, returned during the integration process. When a new set of abscissae are generated the value of :math:`\mathrm{sid}` is incremented by :math:`1`. Advanced users may store calculations required for an identified set :math:`\mathbf{x}`, and reuse them should ``dim1_gen_vec_multi_rcomm`` return the same value of :math:`\mathrm{sid}`, i.e., the same set of abscissae was used.
**nx** : int
`On intermediate exit`: :math:`n_x`, the number of abscissae at which integrands are required.
.. _d01ra-py2-py-other_params:
**Other Parameters**
**'Absolute Interval Minimum'** : float
Default :math:`\text{} = 128.0\epsilon`
:math:`r = \delta_a`, the absolute lower limit for a segment to be considered for subdivision.
See also 'Relative Interval Minimum' and `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fcomments>`__.
Constraint: :math:`r\geq 128\epsilon`.
**'Absolute Tolerance'** : float
Default :math:`\text{} = 1024\epsilon`
:math:`r = \epsilon_a`, the absolute tolerance required.
See also 'Relative Tolerance' and :ref:`Notes <d01ra-py2-py-notes>`.
Constraint: :math:`r\geq 0.0`.
**'Extrapolation'** : str
Default :math:`\text{} = \mathrm{ON}`
Activate or deactivate the use of the :math:`\epsilon` algorithm (Wynn (1956)). 'Extrapolation' often reduces the number of iterations required to achieve the desired solution, but it can occasionally lead to premature convergence towards an incorrect answer.
:math:`\mathrm{ON}`
Use extrapolation.
:math:`\mathrm{OFF}`
Disable extrapolation.
**'Extrapolation Safeguard'** : float
Default :math:`\text{} = 1.0e-12`
:math:`r = \epsilon_{\textit{safe}}`.
If :math:`\epsilon_q` is the estimated error from the quadrature evaluation alone, and :math:`\epsilon_{\textit{ex}}` is the error estimate determined using extrapolation, then the extrapolated solution will only be accepted if :math:`\epsilon_{\textit{safe}}\epsilon_q\leq \epsilon_{\textit{ex}}`.
**'Maximum Subdivisions'** : int
Default :math:`\text{} = 50`
:math:`i = \mathrm{max}_{\textit{sdiv}}`, the maximum number of subdivisions the algorithm may use in the adaptive phase, forming at most an additional :math:`\left(2\times \mathrm{max}_{\textit{sdiv}}\right)` segments.
**'Primary Divisions'** : int
Default :math:`\text{} = 1`
:math:`i = s_{\textit{pri}}`, the number of initial segments of the domain :math:`\left[a, b\right]`.
By default the initial segment is the entire domain.
Constraint: :math:`0 < i < 1000000`.
**'Primary Division Mode'** : str
Default :math:`\text{} = \texttt{'AUTOMATIC'}`
Determines how the initial set of :math:`s_{\textit{pri}}` segments will be generated.
AUTOMATIC
``dim1_gen_vec_multi_rcomm`` will automatically generate :math:`s_{\textit{pri}}` segments of equal size covering the interval :math:`\left[a, b\right]`.
MANUAL
``dim1_gen_vec_multi_rcomm`` will use the break-points :math:`x_{\textit{i}}^0`, for :math:`\textit{i} = 1,2,\ldots,s_{\textit{pri}}-1`, supplied in :math:`\mathrm{x}` on initial entry to generate the initial segments covering :math:`\left[a, b\right]`. These may be supplied in any order, however it will be more efficient to supply them in ascending (or descending if :math:`a > b`) order. Repeated break-points are allowed, although this will generate fewer initial segments.
Note: an absolute bound on the size of an initial segment of :math:`10.0\epsilon` is automatically applied in all cases, and will result in fewer initial subdivisions being generated if automatically generated or supplied break-points result in segments smaller than this.
**'Prioritize Error'** : str
Default :math:`\text{} = \texttt{'LEVEL'}`
Indicates how new subdivisions of segments sustaining unacceptable local errors for integrals should be prioritized.
:math:`\text{LEVEL}`
Segments with lower level with unsatisfactory error estimates will be chosen over segments with greater error on higher levels. This will probably lead to more integrals being improved in earlier iterations of the algorithm, and hence will probably lead to fewer repeated returns (see argument :math:`\mathrm{sid}`), and to more integrals being satisfactorily estimated if computational exhaustion occurs.
:math:`\text{MAXERR}`
The segment with the worst overall error will be split, regardless of level. This will more rapidly improve the worst integral estimates, although it will probably result in the fewest integrals being improved in earlier iterations, and may hence lead to more repeated returns (see argument :math:`\mathrm{sid}`), and potentially fewer integrals satisfying the requested tolerances if computational exhaustion occurs.
**'Quadrature Rule'** : str
Default :math:`\text{} = \text{GK15}`
The basic quadrature rule to be used during the integration.
Currently :math:`6` Gauss--Kronrod rules are available, all identifiable by the letters GK followed by the number of points required by the Kronrod rule.
Higher order rules generally provide higher accuracy with fewer subdivisons.
However, for integrands with sharp singularities, lower order rules may be more efficient, particularly if the integrand away from the singularity is well behaved.
With higher order rules, you may need to increase the 'Absolute Interval Minimum' and the 'Relative Interval Minimum' to maintain numerical difference between the abscissae and the segment bounds.
GK15
The Gauss--Kronrod rule based on :math:`7` Gauss points and :math:`15` Kronrod points.
GK21
The Gauss--Kronrod rule based on :math:`10` Gauss points and :math:`21` Kronrod points. This is the rule used by :meth:`dim1_fin_general`.
GK31
The Gauss--Kronrod rule based on :math:`15` Gauss points and :math:`31` Kronrod points.
GK41
The Gauss--Kronrod rule based on :math:`20` Gauss points and :math:`41` Kronrod points.
GK51
The Gauss--Kronrod rule based on :math:`25` Gauss points and :math:`51` Kronrod points.
GK61
The Gauss--Kronrod rule based on :math:`30` Gauss points and :math:`61` Kronrod points. This is the highest order rule, most suitable for highly oscilliatory integrals.
**'Relative Interval Minimum'** : float
Default :math:`\text{} = 1.0e-6`
:math:`r = \delta_r`, the relative factor in the lower limit, :math:`\delta_r\left\lvert b-a\right\rvert`, for a segment to be considered for subdivision.
See also 'Absolute Interval Minimum' and `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fcomments>`__.
Constraint: :math:`r\geq 0.0`.
**'Relative Tolerance'** : float
Default :math:`\text{} = \sqrt{\epsilon }`
:math:`r = \epsilon_r`, the required relative tolerance.
See also 'Absolute Tolerance' and :ref:`Notes <d01ra-py2-py-notes>`.
Constraint: :math:`r\geq 0.0`.
Note: setting both :math:`\epsilon_r = \epsilon_a = 0.0` is possible, although it will most likely result in an excessive amount of computational effort.
**'Index LDI'** : int
query only
:math:`I_{\textit{ldi}}`, the index of :math:`\mathrm{comm}`\ ['icom'] required for obtaining :math:`\textit{ldi}`.
See `Details of the Computation <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fc-computation>`__.
**'Index LDR'** : int
query only
:math:`I_{\textit{ldr}}`, the index of :math:`\mathrm{comm}`\ ['icom'] required for obtaining :math:`\textit{ldr}`.
See `Details of the Computation <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fc-computation>`__.
**'Index NSDIV'** : int
query only
:math:`I_{\textit{nsdiv}}`, the index of :math:`\mathrm{comm}`\ ['icom'] required for obtaining :math:`\textit{nsdiv}`.
See `Details of the Computation <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fc-computation>`__.
**'Index NSEG'** : int
query only
:math:`I_{\textit{nseg}}`, the index of :math:`\mathrm{comm}`\ ['icom'] required for obtaining :math:`\textit{nseg}`.
See `Details of the Computation <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fc-computation>`__.
**'Index FCP'** : int
query only
:math:`I_{\textit{fcp}}`, the index of :math:`\mathrm{comm}`\ ['icom'] required for obtaining :math:`\textit{fcp}`.
See `Details of the Computation <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fc-computation>`__.
**'Index EVALSP'** : int
query only
:math:`I_{\textit{evalsp}}`, the index of :math:`\mathrm{comm}`\ ['icom'] required for obtaining :math:`\textit{evalsp}`.
See `Details of the Computation <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fc-computation>`__.
**'Index DSP'** : int
query only
:math:`I_{\textit{dsp}}`, the index of :math:`\mathrm{comm}`\ ['icom'] required for obtaining :math:`\textit{dsp}`.
See `Details of the Computation <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fc-computation>`__.
**'Index ESP'** : int
query only
:math:`I_{\textit{esp}}`, the index of :math:`\mathrm{comm}`\ ['icom'] required for obtaining :math:`\textit{esp}`.
See `Details of the Computation <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fc-computation>`__.
**'Index SINFOIP'** : int
query only
:math:`I_{\textit{sinfoip}}`, the index of :math:`\mathrm{comm}`\ ['icom'] required for obtaining :math:`\textit{sinfoip}`.
See `Details of the Computation <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fc-computation>`__.
**'Index SINFORP'** : int
query only
:math:`I_{\textit{sinforp}}`, the index of :math:`\mathrm{comm}`\ ['icom'] required for obtaining :math:`\textit{sinforp}`.
See `Details of the Computation <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01raf.html#fc-computation>`__.
.. _d01ra-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`11`)
:math:`\mathrm{irevcm}` had an illegal value.
On entry, :math:`\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`21`)
On entry, :math:`\textit{ni} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ni}\geq 1`.
(`errno` :math:`71`)
On entry, :math:`\text{‘Primary Division Mode'} = \texttt{'MANUAL'}` and at least one supplied break-point in :math:`\mathrm{x}` is outside of the domain of integration.
(`errno` :math:`81`)
:math:`\textit{lenx}` is insufficient for the chosen options.
On entry, :math:`\textit{lenx} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenx}\geq \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1001`)
Either the option arrays :math:`\mathrm{comm}`\ ['iopts'] and :math:`\mathrm{comm}`\ ['opts'] have not been initialized for ``dim1_gen_vec_multi_rcomm``, or they have become corrupted.
(`errno` :math:`1101`)
On entry, one of :math:`\mathrm{comm}`\ ['icom'] and :math:`\mathrm{comm}`\ ['com'] has become corrupted.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`-1`)
Evaluation of all integrals has been stopped during the initial phase.
(`errno` :math:`1`)
At least one error estimate exceeded the requested tolerances.
(`errno` :math:`2`)
Extremely bad behaviour was detected for at least one integral.
(`errno` :math:`3`)
Extremely bad behaviour was detected for at least one integral. At least one other integral error estimate was above the requested tolerance.
.. _d01ra-py2-py-notes:
**Notes**
``dim1_gen_vec_multi_rcomm`` is an extension to various QUADPACK routines, including QAG, QAGS and QAGP.
The extensions made allow multiple integrands to be evaluated simultaneously, using a vectorized interface and reverse communication.
The quadrature scheme employed by ``dim1_gen_vec_multi_rcomm`` can be chosen by you.
Six Gauss--Kronrod schemes are available.
The algorithm incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)), optionally together with the ε-algorithm (see Wynn (1956)) to perform extrapolation.
The local error estimation is described in Piessens `et al.` (1983).
``dim1_gen_vec_multi_rcomm`` is the integration function in the suite of functions ``dim1_gen_vec_multi_rcomm`` and :meth:`dim1_gen_vec_multi_dimreq`.
It also uses options, which can be set and queried using the functions :meth:`opt_set` and :meth:`opt_get` respectively.
The options available are described in :ref:`Other Parameters <d01ra-py2-py-other_params>`.
The algorithm used by ``dim1_gen_vec_multi_rcomm`` is divided into an `initial solve phase` and an `adaptive solve phase`.
During the initial solve phase, the first estimation of the definite integral and error estimate is constructed over the interval :math:`\left[a, b\right]`.
This will have been divided into :math:`s_{\textit{pri}}` level :math:`1` segments, where :math:`s_{\textit{pri}}` is the number of 'Primary Divisions', and will use any provided break-points if :math:`\text{‘Primary Division Mode'} = \texttt{'MANUAL'}`.
Once a complete integral estimate over :math:`\left[a, b\right]` is available, i.e., after all the estimates for the level :math:`1` segments have been evaluated, the function enters the adaptive phase.
The estimated errors are tested against the requested tolerances :math:`\epsilon_a` and :math:`\epsilon_r`, corresponding to the 'Absolute Tolerance' and 'Relative Tolerance' respectively.
Should this test fail, and additional subdivision be allowed, a segment is selected for subdivision, and is subsequently replaced by two new segments at the next level of refinement.
How this segment is chosen may be altered by setting 'Prioritize Error' to either favour the segment with the maximum error, or the segment with the lowest level supporting an unacceptable (although potentially non-maximal) error.
Up to :math:`\mathrm{max}_{\textit{sdiv}}` subdivisions are allowed if sufficient memory is provided, where :math:`\mathrm{max}_{\textit{sdiv}}` is the value of 'Maximum Subdivisions'.
Once a sufficient number of error estimates have been constructed for a particular integral, the function may optionally use 'Extrapolation' to attempt to accelerate convergence.
This may significantly lower the amount of work required for a given integration.
To minimize the risk of premature convergence from extrapolation, a safeguard :math:`\epsilon_{\textit{safe}}` can be set using 'Extrapolation Safeguard', and the extrapolated solution will only be considered if :math:`\epsilon_{\textit{safe}}\epsilon_q\leq \epsilon_{\textit{ex}}`, where :math:`\epsilon_q` and :math:`\epsilon_{\textit{ex}}` are the estimated error directly from the quadrature and from the extrapolation respectively.
If extrapolation is successful for the computation of integral :math:`j`, the extrapolated solution will be returned in :math:`\mathrm{dinest}[j-1]` on completion of ``dim1_gen_vec_multi_rcomm``.
Otherwise the direct solution will be returned in :math:`\mathrm{dinest}[j-1]`.
This is indicated by the value of :math:`\mathrm{needi}[j-1]` on completion.
.. _d01ra-py2-py-references:
**References**
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, 1973, `An algorithm for automatic integration`, Angew. Inf. (15), 399--401
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_gen_vec_multi_dimreq(ni, iopts, opts):
r"""
The dimension of the arrays that must be passed as actual arguments to :meth:`dim1_gen_vec_multi_rcomm` are dependent upon a number of factors. ``dim1_gen_vec_multi_dimreq`` returns the correct size of these arrays enabling :meth:`dim1_gen_vec_multi_rcomm` to be called successfully.
.. _d01rc-py2-py-doc:
For full information please refer to the NAG Library document for d01rc
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rcf.html
.. _d01rc-py2-py-parameters:
**Parameters**
**ni** : int
:math:`n_i`, the number of integrals which will be approximated in the subsequent call to :meth:`dim1_gen_vec_multi_rcomm`.
**iopts** : int, array-like, shape :math:`\left(100\right)`
The integer option array as returned by :meth:`opt_set`.
**opts** : float, array-like, shape :math:`\left(100\right)`
The real option array as returned by :meth:`opt_set`.
**Returns**
**lenxrq** : int
:math:`\textit{lenxrq}`, the minimum dimension of the array :math:`\textit{x}` that can be used in a subsequent call to :meth:`dim1_gen_vec_multi_rcomm`.
**ldfmrq** : int
:math:`\textit{ldfmrq}`, the minimum leading dimension of the array :math:`\textit{fm}` that can be used in a subsequent call to :meth:`dim1_gen_vec_multi_rcomm`.
**sdfmrq** : int
:math:`\textit{sdfmrq}`, the minimum second dimension of the array :math:`\textit{fm}` that can be used in a subsequent call to :meth:`dim1_gen_vec_multi_rcomm`.
Note: the minimum dimension of the array :math:`\textit{fm}` is :math:`\textit{ldfmrq}\times \textit{sdfmrq}`.
**licmin** : int
:math:`\textit{licmin}`, the minimum dimension of the array :math:`\textit{icom}` that must be passed to :meth:`dim1_gen_vec_multi_rcomm` to enable it to calculate a single approximation to all the :math:`n_i` integrals over the interval :math:`\left[a, b\right]` with :math:`s_{\textit{pri}}` initial segments.
**licmax** : int
:math:`\textit{licmax}` the dimension of the array :math:`\textit{icom}` that must be passed to :meth:`dim1_gen_vec_multi_rcomm` to enable it to exhaust the adaptive process controlled by the currently set options for the :math:`n_i` integrals over the interval :math:`\left[a, b\right]` with :math:`s_{\textit{pri}}` initial segments.
**lcmin** : int
:math:`\textit{lcmin}`, the minimum dimension of the array :math:`\textit{com}` that must be passed to :meth:`dim1_gen_vec_multi_rcomm` to enable it to calculate a single approximation to all the :math:`n_i` integrals over the interval :math:`\left[a, b\right]` with :math:`s_{\textit{pri}}` initial segments.
**lcmax** : int
:math:`\textit{lcmax}`, the dimension of the array :math:`\textit{com}` that must be passed to :meth:`dim1_gen_vec_multi_rcomm` to enable it to exhaust the adaptive process controlled by the currently set options for the :math:`n_i` integrals over the interval :math:`\left[a, b\right]` with :math:`s_{\textit{pri}}` initial segments.
.. _d01rc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`21`)
On entry, :math:`\mathrm{ni} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ni} > 0`.
(`errno` :math:`1001`)
One of the option arrays :math:`\mathrm{iopts}` or :math:`\mathrm{opts}` has become corrupted. Re-initialize the arrays using :meth:`opt_set`.
.. _d01rc-py2-py-notes:
**Notes**
``dim1_gen_vec_multi_dimreq`` returns the minimum dimension of the arrays :math:`\textit{x}` (:math:`\textit{lenxrq}`), :math:`\textit{fm}` (:math:`\textit{ldfmrq}\times \textit{sdfmrq}`), :math:`\textit{icom}` (:math:`\textit{licmin}`) and :math:`\textit{com}` (:math:`\textit{lcmin}`) that must be passed to :meth:`dim1_gen_vec_multi_rcomm` to enable the integration to commence given options currently set for the :math:`\mathrm{ni}` integrands. ``dim1_gen_vec_multi_dimreq`` also returns the upper bounds :math:`\textit{licmax}` and :math:`\textit{lcmax}` for the dimension of the arrays :math:`\textit{icom}` and :math:`\textit{com}`, that could possibly be required with the chosen options.
All the minimum values :math:`\textit{lenxrq}`, :math:`\textit{ldfmrq}`, :math:`\textit{sdfmrq}`, :math:`\textit{licmin}` and :math:`\textit{lcmin}`, and subsequently all the maximum values :math:`\textit{licmax}` and :math:`\textit{lcmax}` may be affected if different options are set, and hence ``dim1_gen_vec_multi_dimreq`` should be called after any options are set, and before the first call to :meth:`dim1_gen_vec_multi_rcomm`.
A segment is here defined as a (possibly maximal) subset of the domain of integration.
During subdivision, a segment is bisected into two new segments.
"""
raise NotImplementedError
[docs]def dim1_fin_gonnet_vec(a, b, f, epsabs, epsrel, data=None):
r"""
``dim1_fin_gonnet_vec`` is a general purpose integrator which calculates an approximation to the integral of a function :math:`f\left(x\right)` over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{.}
The function is suitable as a general purpose integrator, and can be used when the integrand has singularities and infinities.
In particular, the function can continue if the function :math:`\mathrm{f}` explicitly returns a quiet or signalling NaN or a signed infinity.
.. _d01rg-py2-py-doc:
For full information please refer to the NAG Library document for d01rg
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rgf.html
.. _d01rg-py2-py-parameters:
**Parameters**
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
Note: if :math:`\mathrm{a} = \mathrm{b}`, the function will immediately return with :math:`\mathrm{dinest} = 0.0`, :math:`\mathrm{errest} = 0.0` and :math:`\mathrm{nevals} = 0`.
**f** : callable (fv, iflag) = f(x, iflag, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f` at a set of points.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{nx}\right)`
The abscissae, :math:`x_i`, for :math:`\textit{i} = 1,2,\ldots,\textit{nx}`, at which function values are required.
**iflag** : int
:math:`\mathrm{iflag} = 0`.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fv** : float, array-like, shape :math:`\left(\textit{nx}\right)`
:math:`\mathrm{fv}` must contain the values of the integrand :math:`f`. :math:`\mathrm{fv}[i-1] = f\left(x_i\right)` for all :math:`i = 1,2,\ldots,\textit{nx}`.
**iflag** : int
Set :math:`\mathrm{iflag} < 0` to force an immediate exit with :math:`\mathrm{errno}` = -1.
**epsabs** : float
The absolute accuracy required.
If :math:`\mathrm{epsabs}` is negative, :math:`\left\lvert \mathrm{epsabs}\right\rvert` is used.
See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rgf.html#accuracy>`__.
If :math:`\mathrm{epsabs} = 0.0`, only the relative error will be used.
**epsrel** : float
The relative accuracy required.
If :math:`\mathrm{epsrel}` is negative, :math:`\left\lvert \mathrm{epsrel}\right\rvert` is used.
See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rgf.html#accuracy>`__.
If :math:`\mathrm{epsrel} = 0.0`, only the absolute error will be used otherwise the actual value of :math:`\mathrm{epsrel}` used by ``dim1_fin_gonnet_vec`` is :math:`\mathrm{max}\left(\text{machine precision}, \left\lvert \mathrm{epsrel}\right\rvert \right)`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**dinest** : float
The estimate of the definite integral :math:`\mathrm{f}`.
**errest** : float
The error estimate of the definite integral :math:`\mathrm{f}`.
**nevals** : int
The total number of points at which the integrand, :math:`f`, has been evaluated.
.. _d01rg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`14`)
Both :math:`\mathrm{epsabs} = 0.0` and :math:`\mathrm{epsrel} = 0.0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`-1`)
Exit requested from :math:`\mathrm{f}` with :math:`\mathrm{iflag} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
The requested accuracy was not achieved. Consider using larger values of :math:`\mathrm{epsabs}` and :math:`\mathrm{epsrel}`.
(`errno` :math:`2`)
The integral is probably divergent or slowly convergent.
.. _d01rg-py2-py-notes:
**Notes**
``dim1_fin_gonnet_vec`` uses the algorithm described in Gonnet (2010).
It is an adaptive algorithm, similar to the QUADPACK routine QAGS (see Piessens `et al.` (1983), see also :meth:`dim1_gen_vec_multi_rcomm`) but includes significant differences regarding how the integrand is represented, how the integration error is estimated and how singularities and divergent integrals are treated.
The local error estimation is described in Gonnet (2010).
``dim1_fin_gonnet_vec`` requires a function to evaluate the integrand at an array of different points and is, therefore, amenable to parallel execution.
.. _d01rg-py2-py-references:
**References**
Gonnet, P, 2010, `Increasing the reliability of adaptive quadrature using explicit interpolants`, ACM Trans. Math. software (37), 26
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
"""
raise NotImplementedError
[docs]def dim1_fin_general(f, a, b, epsabs, epsrel, maxsub, data=None):
r"""
``dim1_fin_general`` is a general purpose integrator which calculates an approximation to the integral of a function :math:`f\left(x\right)` over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{.}
.. _d01rj-py2-py-doc:
For full information please refer to the NAG Library document for d01rj
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rjf.html
.. _d01rj-py2-py-parameters:
**Parameters**
**f** : callable (fv, iflag) = f(x, iflag, data=None)
:math:`\mathrm{f}` must return the values of the integrand :math:`f` at a set of points.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{nx}\right)`
The abscissae, :math:`x_i`, for :math:`\textit{i} = 1,2,\ldots,\textit{nx}`, at which function values are required.
**iflag** : int
:math:`\mathrm{iflag} = 0`.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fv** : float, array-like, shape :math:`\left(\textit{nx}\right)`
:math:`\mathrm{fv}` must contain the values of the integrand :math:`f`. :math:`\mathrm{fv}[i-1] = f\left(x_i\right)` for all :math:`i = 1,2,\ldots,\textit{nx}`.
**iflag** : int
Set :math:`\mathrm{iflag} < 0` to force an immediate exit with :math:`\mathrm{errno}` = -1.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
Note: if :math:`\mathrm{a} = \mathrm{b}`, the function will immediately return with :math:`\mathrm{result} = 0.0`, :math:`\mathrm{abserr} = 0.0`, :math:`\mathrm{rinfo} = 0.0` and :math:`\mathrm{iinfo} = 0`.
**epsabs** : float
:math:`\epsilon_a`, the absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, :math:`\epsilon_a = \left\lvert \mathrm{epsabs}\right\rvert`. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rjf.html#accuracy>`__.
**epsrel** : float
:math:`\epsilon_r`, the relative accuracy required. If :math:`\mathrm{epsrel}` is negative, :math:`\epsilon_r = \left\lvert \mathrm{epsrel}\right\rvert`. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rjf.html#accuracy>`__.
**maxsub** : int
:math:`\mathrm{max}_{\textit{sdiv}}`, the upper bound on the total number of subdivisions ``dim1_fin_general`` may use to generate new segments. If :math:`\mathrm{max}_{\textit{sdiv}} = 1`, only the initial segment will be evaluated.
`Suggested value`: a value in the range :math:`200` to :math:`500` is adequate for most problems.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**rinfo** : float, ndarray, shape :math:`\left(4\times \mathrm{maxsub}\right)`
Details of the computation. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rjf.html#fcomments>`__ for more information.
**iinfo** : int, ndarray, shape :math:`\left(\max\left(\mathrm{maxsub},4\right)\right)`
Details of the computation. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rjf.html#fcomments>`__ for more information.
.. _d01rj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`61`)
On entry, :math:`\mathrm{maxsub} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{maxsub}\geq 1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`-1`)
Exit from :math:`\mathrm{f}` with :math:`\mathrm{iflag} < 0`.
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{maxsub}`) has been reached: :math:`\mathrm{maxsub} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
(`errno` :math:`4`)
Round-off error is detected in the extrapolation table.
(`errno` :math:`5`)
The integral is probably divergent or slowly convergent.
.. _d01rj-py2-py-notes:
**Notes**
``dim1_fin_general`` is based on the QUADPACK routine QAGS (see Piessens `et al.` (1983)).
It is an adaptive function, using the Gauss :math:`10`-point and Kronrod :math:`21`-point rules.
The algorithm, described in de Doncker (1978), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the :math:`\epsilon`-algorithm (see Wynn (1956)) to perform extrapolation.
The local error estimation is described in Piessens `et al.` (1983).
The function is suitable as a general purpose integrator, and can be used when the integrand has singularities, especially when these are of algebraic or logarithmic type.
``dim1_fin_general`` requires you to supply a function to evaluate the integrand at an array of points.
.. _d01rj-py2-py-references:
**References**
de Doncker, E, 1978, `An adaptive extrapolation algorithm for automatic integration`, ACM SIGNUM Newsl. (13(2)), 12--18
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_fin_osc_fn(f, a, b, epsabs, epsrel, maxsub, key=6, data=None):
r"""
``dim1_fin_osc_fn`` is an adaptive integrator, especially suited to oscillating, nonsingular integrands, which calculates an approximation to the integral of a function :math:`f\left(x\right)` over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{.}
.. _d01rk-py2-py-doc:
For full information please refer to the NAG Library document for d01rk
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rkf.html
.. _d01rk-py2-py-parameters:
**Parameters**
**f** : callable (fv, iflag) = f(x, iflag, data=None)
:math:`\mathrm{f}` must return the values of the integrand :math:`f` at a set of points.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{nx}\right)`
The abscissae, :math:`x_i`, for :math:`\textit{i} = 1,2,\ldots,\textit{nx}`, at which function values are required.
**iflag** : int
:math:`\mathrm{iflag} = 0`.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fv** : float, array-like, shape :math:`\left(\textit{nx}\right)`
:math:`\mathrm{fv}` must contain the values of the integrand :math:`f`. :math:`\mathrm{fv}[i-1] = f\left(x_i\right)` for all :math:`i = 1,2,\ldots,\textit{nx}`.
**iflag** : int
Set :math:`\mathrm{iflag} < 0` to force an immediate exit with :math:`\mathrm{errno}` = -1.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
Note: if :math:`\mathrm{a} = \mathrm{b}`, the function will immediately return with :math:`\mathrm{result} = 0.0`, :math:`\mathrm{abserr} = 0.0`, :math:`\mathrm{rinfo} = 0.0` and :math:`\mathrm{iinfo} = 0`.
**epsabs** : float
:math:`\epsilon_a`, the absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, :math:`\epsilon_a = \left\lvert \mathrm{epsabs}\right\rvert`. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rkf.html#accuracy>`__.
**epsrel** : float
:math:`\epsilon_r`, the relative accuracy required. If :math:`\mathrm{epsrel}` is negative, :math:`\epsilon_r = \left\lvert \mathrm{epsrel}\right\rvert`. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rkf.html#accuracy>`__.
**maxsub** : int
:math:`\mathrm{max}_{\textit{sdiv}}`, the upper bound on the total number of subdivisions ``dim1_fin_osc_fn`` may use to generate new segments. If :math:`\mathrm{max}_{\textit{sdiv}} = 1`, only the initial segment will be evaluated.
`Suggested value`: a value in the range :math:`200` to :math:`500` is adequate for most problems.
**key** : int, optional
Indicates which integration rule is to be used. The number of function evaluations required for an integral estimate over any segment will be the number of Kronrod points, :math:`n_{\mathrm{kron}}`.
:math:`\mathrm{key} = 1`
For the Gauss :math:`7`-point and Kronrod :math:`15`-point rule.
:math:`\mathrm{key} = 2`
For the Gauss :math:`10`-point and Kronrod :math:`21`-point rule.
:math:`\mathrm{key} = 3`
For the Gauss :math:`15`-point and Kronrod :math:`31`-point rule.
:math:`\mathrm{key} = 4`
For the Gauss :math:`20`-point and Kronrod :math:`41`-point rule.
:math:`\mathrm{key} = 5`
For the Gauss :math:`25`-point and Kronrod :math:`51`-point rule.
:math:`\mathrm{key} = 6`
For the Gauss :math:`30`-point and Kronrod :math:`61`-point rule.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**rinfo** : float, ndarray, shape :math:`\left(4\times \mathrm{maxsub}\right)`
Details of the computation. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rkf.html#fcomments>`__ for more information.
**iinfo** : int, ndarray, shape :math:`\left(\max\left(\mathrm{maxsub},4\right)\right)`
Details of the computation. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rkf.html#fcomments>`__ for more information.
.. _d01rk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`41`)
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{key} = 1`, :math:`2`, :math:`3`, :math:`4`, :math:`5` or :math:`6`.
(`errno` :math:`71`)
On entry, :math:`\mathrm{maxsub} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{maxsub}\geq 1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`-1`)
Exit from :math:`\mathrm{f}` with :math:`\mathrm{iflag} < 0`.
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{maxsub}`) has been reached: :math:`\mathrm{maxsub} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
.. _d01rk-py2-py-notes:
**Notes**
``dim1_fin_osc_fn`` is based on the QUADPACK routine QAG (see Piessens `et al.` (1983)).
It is an adaptive function, offering a choice of six Gauss--Kronrod rules.
A 'global' acceptance criterion (as defined by Malcolm and Simpson (1976)) is used.
The local error estimation is described in Piessens `et al.` (1983).
Because ``dim1_fin_osc_fn`` is based on integration rules of high order, it is especially suitable for nonsingular oscillating integrands.
``dim1_fin_osc_fn`` requires you to supply a function to evaluate the integrand at an array of points.
.. _d01rk-py2-py-references:
**References**
de Doncker, E, 1978, `An adaptive extrapolation algorithm for automatic integration`, ACM SIGNUM Newsl. (13(2)), 12--18
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_fin_brkpts(f, a, b, points, epsabs, epsrel, maxsub, data=None):
r"""
``dim1_fin_brkpts`` is a general purpose integrator which calculates an approximation to the integral of a function :math:`f\left(x\right)` over a finite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{,}
where the integrand may have local singular behaviour at a finite number of points within the integration interval.
.. _d01rl-py2-py-doc:
For full information please refer to the NAG Library document for d01rl
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rlf.html
.. _d01rl-py2-py-parameters:
**Parameters**
**f** : callable (fv, iflag) = f(x, iflag, data=None)
:math:`\mathrm{f}` must return the values of the integrand :math:`f` at a set of points.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{nx}\right)`
The abscissae, :math:`x_i`, for :math:`\textit{i} = 1,2,\ldots,\textit{nx}`, at which function values are required.
**iflag** : int
:math:`\mathrm{iflag} = 0`.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fv** : float, array-like, shape :math:`\left(\textit{nx}\right)`
:math:`\mathrm{fv}` must contain the values of the integrand :math:`f`. :math:`\mathrm{fv}[i-1] = f\left(x_i\right)` for all :math:`i = 1,2,\ldots,\textit{nx}`.
**iflag** : int
Set :math:`\mathrm{iflag} < 0` to force an immediate exit with :math:`\mathrm{errno}` = -1.
**a** : float
:math:`a`, the lower limit of integration.
**b** : float
:math:`b`, the upper limit of integration. It is not necessary that :math:`a < b`.
Note: if :math:`\mathrm{a} = \mathrm{b}`, the function will immediately return with :math:`\mathrm{result} = 0.0`, :math:`\mathrm{abserr} = 0.0`, :math:`\mathrm{rinfo} = 0.0` and :math:`\mathrm{iinfo} = 0`.
**points** : float, array-like, shape :math:`\left(\textit{npts}\right)`
The user-specified break-points.
**epsabs** : float
:math:`\epsilon_a`, the absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, :math:`\epsilon_a = \left\lvert \mathrm{epsabs}\right\rvert`. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rlf.html#accuracy>`__.
**epsrel** : float
:math:`\epsilon_r`, the relative accuracy required. If :math:`\mathrm{epsrel}` is negative, :math:`\epsilon_r = \left\lvert \mathrm{epsrel}\right\rvert`. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rlf.html#accuracy>`__.
**maxsub** : int
:math:`\mathrm{max}_{\textit{sdiv}}`, the upper bound on the total number of subdivisions ``dim1_fin_brkpts`` may use to generate new segments. This does not include the initial segments of the interval generated from the supplied break-points. If :math:`\mathrm{max}_{\textit{sdiv}} = 1`, only the initial segments will be evaluated.
`Suggested value`: a value in the range :math:`200` to :math:`500` is adequate for most problems.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**rinfo** : float, ndarray, shape :math:`\left(4\times \max\left(\mathrm{maxsub},\textit{npts}\right)+\textit{npts}+6\right)`
Details of the computation. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rlf.html#fcomments>`__ for more information.
**iinfo** : int, ndarray, shape :math:`\left(2\times \max\left(\mathrm{maxsub},\textit{npts}\right)+\textit{npts}+4\right)`
Details of the computation. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rlf.html#fcomments>`__ for more information.
.. _d01rl-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`41`)
On entry, :math:`\textit{npts} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{npts}\geq 0`.
(`errno` :math:`51`)
On entry, break-points are specified outside :math:`\left(\mathrm{a}, \mathrm{b}\right)`: :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`81`)
On entry, :math:`\mathrm{maxsub} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{maxsub}\geq 1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`-1`)
Exit from :math:`\mathrm{f}` with :math:`\mathrm{iflag} < 0`.
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{maxsub}`) has been reached: :math:`\mathrm{maxsub} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
(`errno` :math:`4`)
Round-off error is detected in the extrapolation table.
(`errno` :math:`5`)
The integral is probably divergent or slowly convergent.
.. _d01rl-py2-py-notes:
**Notes**
``dim1_fin_brkpts`` is based on the QUADPACK routine QAGP (see Piessens `et al.` (1983)).
It is very similar to :meth:`dim1_fin_general`, but allows you to supply 'break-points', points at which the integrand is known to be difficult.
It employs an adaptive algorithm, using the Gauss :math:`10`-point and Kronrod :math:`21`-point rules.
The algorithm, described in de Doncker (1978), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the :math:`\epsilon`-algorithm (see Wynn (1956)) to perform extrapolation.
The user-supplied 'break-points' always occur as the end points of some sub-interval during the adaptive process.
The local error estimation is described in Piessens `et al.` (1983).
``dim1_fin_brkpts`` requires you to supply a function to evaluate the integrand at an array of points.
.. _d01rl-py2-py-references:
**References**
de Doncker, E, 1978, `An adaptive extrapolation algorithm for automatic integration`, ACM SIGNUM Newsl. (13(2)), 12--18
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_inf_general(f, bound, inf, epsabs, epsrel, maxsub, data=None):
r"""
``dim1_inf_general`` calculates an approximation to the integral of a function :math:`f\left(x\right)` over an infinite or semi-infinite interval :math:`\left[a, b\right]`:
.. math::
I = \int_a^bf\left(x\right){dx}\text{.}
.. _d01rm-py2-py-doc:
For full information please refer to the NAG Library document for d01rm
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rmf.html
.. _d01rm-py2-py-parameters:
**Parameters**
**f** : callable (fv, iflag) = f(x, iflag, data=None)
:math:`\mathrm{f}` must return the values of the integrand :math:`f` at a set of points.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{nx}\right)`
The abscissae, :math:`x_i`, for :math:`\textit{i} = 1,2,\ldots,\textit{nx}`, at which function values are required.
**iflag** : int
:math:`\mathrm{iflag} = 0`.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fv** : float, array-like, shape :math:`\left(\textit{nx}\right)`
:math:`\mathrm{fv}` must contain the values of the integrand :math:`f`. :math:`\mathrm{fv}[i-1] = f\left(x_i\right)` for all :math:`i = 1,2,\ldots,\textit{nx}`.
**iflag** : int
Set :math:`\mathrm{iflag} < 0` to force an immediate exit with :math:`\mathrm{errno}` = -1.
**bound** : float
The finite limit of the integration range (if present). :math:`\mathrm{bound}` is not used if the interval is doubly infinite.
**inf** : int
Indicates the kind of integration range.
:math:`\mathrm{inf} = 1`
The range is :math:`\left[\mathrm{bound}, {{+\infty }}\right)`.
:math:`\mathrm{inf} = -1`
The range is :math:`\left({{-\infty }}, \mathrm{bound}\right]`.
:math:`\mathrm{inf} = 2`
The range is :math:`\left({{-\infty }}, {{+\infty }}\right)`.
**epsabs** : float
:math:`\epsilon_a`, the absolute accuracy required. If :math:`\mathrm{epsabs}` is negative, :math:`\epsilon_a = \left\lvert \mathrm{epsabs}\right\rvert`. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rmf.html#accuracy>`__.
**epsrel** : float
:math:`\epsilon_r`, the relative accuracy required. If :math:`\mathrm{epsrel}` is negative, :math:`\epsilon_r = \left\lvert \mathrm{epsrel}\right\rvert`. See `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rmf.html#accuracy>`__.
**maxsub** : int
:math:`\mathrm{max}_{\textit{sdiv}}`, the upper bound on the total number of subdivisions ``dim1_inf_general`` may use to generate new segments. If :math:`\mathrm{max}_{\textit{sdiv}} = 1`, only the initial segment will be evaluated.
`Suggested value`: a value in the range :math:`200` to :math:`500` is adequate for most problems.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**result** : float
The approximation to the integral :math:`I`.
**abserr** : float
An estimate of the modulus of the absolute error, which should be an upper bound for :math:`\left\lvert I-\mathrm{result}\right\rvert`.
**rinfo** : float, ndarray, shape :math:`\left(4\times \mathrm{maxsub}\right)`
Details of the computation. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rmf.html#fcomments>`__ for more information.
**iinfo** : int, ndarray, shape :math:`\left(\max\left(\mathrm{maxsub},4\right)\right)`
Details of the computation. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01rmf.html#fcomments>`__ for more information.
.. _d01rm-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`31`)
On entry, :math:`\mathrm{inf} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{inf} = -1`, :math:`1` or :math:`2`.
(`errno` :math:`61`)
On entry, :math:`\mathrm{maxsub} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{maxsub}\geq 1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`-1`)
Exit from :math:`\mathrm{f}` with :math:`\mathrm{iflag} < 0`.
(`errno` :math:`1`)
The maximum number of subdivisions (:math:`\mathrm{maxsub}`) has been reached: :math:`\mathrm{maxsub} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Round-off error prevents the requested tolerance from being achieved: :math:`\mathrm{epsabs} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{epsrel} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
Extremely bad integrand behaviour occurs around the sub-interval :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)`.
(`errno` :math:`4`)
Round-off error is detected in the extrapolation table.
(`errno` :math:`5`)
The integral is probably divergent or slowly convergent.
.. _d01rm-py2-py-notes:
**Notes**
``dim1_inf_general`` is based on the QUADPACK routine QAGI (see Piessens `et al.` (1983)).
The entire infinite integration range is first transformed to :math:`\left[0, 1\right]` using one of the identities:
.. math::
\int_{{-\infty }}^af\left(x\right){dx} = \int_0^1f\left(a-\frac{{1-t}}{t}\right)\frac{1}{t^2}{dt}
.. math::
\int_a^{\infty }f\left(x\right){dx} = \int_0^1f\left(a+\frac{{1-t}}{t}\right)\frac{1}{t^2}{dt}
.. math::
\int_{{-\infty }}^{\infty }f\left(x\right){dx} = \int_0^{\infty }\left(f\left(x\right)+f\left(-x\right)\right){dx} = \int_0^1\text{ }\left[f\left(\frac{{1-t}}{t}\right)+f\left(\frac{{-1+t}}{t}\right)\right]\frac{1}{t^2}{dt}\text{,}
where :math:`a` represents a finite integration limit.
An adaptive procedure, based on the Gauss :math:`7`-point and Kronrod :math:`15`-point rules, is then employed on the transformed integral.
The algorithm, described in de Doncker (1978), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the :math:`\epsilon`-algorithm (see Wynn (1956)) to perform extrapolation.
The local error estimation is described in Piessens `et al.` (1983).
``dim1_inf_general`` requires you to supply a function to evaluate the integrand at an array of points.
.. _d01rm-py2-py-references:
**References**
de Doncker, E, 1978, `An adaptive extrapolation algorithm for automatic integration`, ACM SIGNUM Newsl. (13(2)), 12--18
Malcolm, M A and Simpson, R B, 1976, `Local versus global strategies for adaptive quadrature`, ACM Trans. Math. Software (1), 129--146
Piessens, R, de Doncker--Kapenga, E, Überhuber, C and Kahaner, D, 1983, `QUADPACK, A Subroutine Package for Automatic Integration`, Springer--Verlag
Wynn, P, 1956, `On a device for computing the` :math:`e_m\left(S_n\right)` `transformation`, Math. Tables Aids Comput. (10), 91--96
"""
raise NotImplementedError
[docs]def dim1_gauss_wres(key, a, b, n):
r"""
``dim1_gauss_wres`` returns the weights and abscissae appropriate to a Gaussian quadrature formula with a specified number of abscissae.
The formulae provided are for Gauss--Legendre, rational Gauss, Gauss--Laguerre and Gauss--Hermite.
.. _d01tb-py2-py-doc:
For full information please refer to the NAG Library document for d01tb
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01tbf.html
.. _d01tb-py2-py-parameters:
**Parameters**
**key** : int
Indicates the quadrature formula.
:math:`\mathrm{key} = 0`
Gauss--Legendre quadrature on a finite interval, using normal weights.
:math:`\mathrm{key} = 3`
Gauss--Laguerre quadrature on a semi-infinite interval, using normal weights.
:math:`\mathrm{key} = -3`
Gauss--Laguerre quadrature on a semi-infinite interval, using adjusted weights.
:math:`\mathrm{key} = 4`
Gauss--Hermite quadrature on an infinite interval, using normal weights.
:math:`\mathrm{key} = -4`
Gauss--Hermite quadrature on an infinite interval, using adjusted weights.
:math:`\mathrm{key} = -5`
Rational Gauss quadrature on a semi-infinite interval, using adjusted weights.
**a** : float
The parameters :math:`a` and :math:`b` which occur in the quadrature formulae described in :ref:`Notes <d01tb-py2-py-notes>`.
**b** : float
The parameters :math:`a` and :math:`b` which occur in the quadrature formulae described in :ref:`Notes <d01tb-py2-py-notes>`.
**n** : int
:math:`n`, the number of weights and abscissae to be returned.
**Returns**
**weight** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
The :math:`\mathrm{n}` weights.
**abscis** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
The :math:`\mathrm{n}` abscissae.
.. _d01tb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`11`)
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{key} = 0`, :math:`3`, :math:`-3`, :math:`4`, :math:`-4` or :math:`-5`.
(`errno` :math:`12`)
The value of :math:`\mathrm{a}` and/or :math:`\mathrm{b}` is invalid for Gauss-Laguerre quadrature.
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
On entry, :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\left\lvert \mathrm{b}\right\rvert > 0.0`.
(`errno` :math:`12`)
The value of :math:`\mathrm{a}` and/or :math:`\mathrm{b}` is invalid for Gauss-Hermite quadrature.
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
On entry, :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{b} > 0.0`.
(`errno` :math:`12`)
The value of :math:`\mathrm{a}` and/or :math:`\mathrm{b}` is invalid for rational Gauss quadrature.
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
On entry, :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\left\lvert \mathrm{a}+\mathrm{b}\right\rvert > 0.0`.
(`errno` :math:`14`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n} > 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The :math:`\mathrm{n}`-point rule is not among those stored.
On entry: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
:math:`\mathrm{n}`-rule used: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Underflow occurred in calculation of normal weights.
Reduce :math:`\mathrm{n}` or use adjusted weights: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
No nonzero weights were generated for the provided parameters.
.. _d01tb-py2-py-notes:
**Notes**
``dim1_gauss_wres`` returns the weights and abscissae for use in the Gaussian quadrature of a function :math:`f\left(x\right)`.
The quadrature takes the form
.. math::
S = \sum_{{i = 1}}^nw_if\left(x_i\right)
where :math:`w_i` are the weights and :math:`x_i` are the abscissae (see Davis and Rabinowitz (1975), Fröberg (1970), Ralston (1965) and Stroud and Secrest (1966)).
Weights and abscissae are available for Gauss--Legendre, rational Gauss, Gauss--Laguerre and Gauss--Hermite quadrature, and for a selection of values of :math:`n` (see :ref:`Parameters <d01tb-py2-py-parameters>`).
(a) Gauss--Legendre Quadrature:
.. math::
S\simeq \int_a^bf\left(x\right){dx}
where :math:`a` and :math:`b` are finite and it will be exact for any function of the form
.. math::
f\left(x\right) = \sum_{{i = 0}}^{{2n-1}}c_ix^i\text{.}
(#) Rational Gauss quadrature, adjusted weights:
.. math::
S\simeq \int_a^{\infty }f\left(x\right){dx}\quad \text{ }\quad \left(a+b > 0\right)\quad \text{ or }\quad S\simeq \int_{{-\infty }}^af\left(x\right){dx}\quad \text{ }\quad \left(a+b < 0\right)
and will be exact for any function of the form
.. math::
f\left(x\right) = \sum_{{i = 2}}^{{2n+1}}\frac{c_i}{\left(x+b\right)^i} = \frac{{\sum_{{i = 0}}^{{2n-1}}c_{{2n+1-i}}\left(x+b\right)^i}}{\left(x+b\right)^{{2n+1}}}\text{.}
(#) Gauss--Laguerre quadrature, adjusted weights:
.. math::
S\simeq \int_a^{\infty }f\left(x\right){dx}\quad \text{ }\quad \left(b > 0\right)\quad \text{ or }\quad S\simeq \int_{{-\infty }}^af\left(x\right){dx}\quad \text{ }\quad \left(b < 0\right)
and will be exact for any function of the form
.. math::
f\left(x\right) = e^{{-bx}}\sum_{{i = 0}}^{{2n-1}}c_ix^i\text{.}
(#) Gauss--Hermite quadrature, adjusted weights:
.. math::
S\simeq \int_{{-\infty }}^{{+\infty }}f\left(x\right){dx}
and will be exact for any function of the form
.. math::
f\left(x\right) = e^{{-b\left(x-a\right)^2}}\sum_{{i = 0}}^{{2n-1}}c_ix^i\quad \text{ }\quad \left(b > 0\right)\text{.}
(#) Gauss--Laguerre quadrature, normal weights:
.. math::
S\simeq \int_a^{\infty }e^{{-bx}}f\left(x\right){dx}\quad \text{ }\quad \left(b > 0\right)\quad \text{ or }\quad S\simeq \int_{{-\infty }}^ae^{{-bx}}f\left(x\right){dx}\quad \text{ }\quad \left(b < 0\right)
and will be exact for any function of the form
.. math::
f\left(x\right) = \sum_{{i = 0}}^{{2n-1}}c_ix^i\text{.}
(#) Gauss--Hermite quadrature, normal weights:
.. math::
S\simeq \int_{{-\infty }}^{{+\infty }}e^{{-b\left(x-a\right)^2}}f\left(x\right){dx}
and will be exact for any function of the form
.. math::
f\left(x\right) = \sum_{{i = 0}}^{{2n-1}}c_ix^i\text{.}
**Note:** the Gauss--Legendre abscissae, with :math:`a = -1`, :math:`b = +1`, are the zeros of the Legendre polynomials; the Gauss--Laguerre abscissae, with :math:`a = 0`, :math:`b = 1`, are the zeros of the Laguerre polynomials; and the Gauss--Hermite abscissae, with :math:`a = 0`, :math:`b = 1`, are the zeros of the Hermite polynomials.
.. _d01tb-py2-py-references:
**References**
Davis, P J and Rabinowitz, P, 1975, `Methods of Numerical Integration`, Academic Press
Fröberg, C E, 1970, `Introduction to Numerical Analysis`, Addison--Wesley
Ralston, A, 1965, `A First Course in Numerical Analysis`, pp. 87--90, McGraw--Hill
Stroud, A H and Secrest, D, 1966, `Gaussian Quadrature Formulas`, Prentice--Hall
"""
raise NotImplementedError
[docs]def dim1_gauss_wgen(itype, a, b, c, d, n):
r"""
``dim1_gauss_wgen`` returns the weights (normal or adjusted) and abscissae for a Gaussian integration rule with a specified number of abscissae.
Six different types of Gauss rule are allowed.
.. _d01tc-py2-py-doc:
For full information please refer to the NAG Library document for d01tc
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01tcf.html
.. _d01tc-py2-py-parameters:
**Parameters**
**itype** : int
Indicates the type of quadrature rule.
:math:`\mathrm{itype} = 0`
Gauss--Legendre, with normal weights.
:math:`\mathrm{itype} = 1`
Gauss--Jacobi, with normal weights.
:math:`\mathrm{itype} = -1`
Gauss--Jacobi, with adjusted weights.
:math:`\mathrm{itype} = 2`
Exponential Gauss, with normal weights.
:math:`\mathrm{itype} = -2`
Exponential Gauss, with adjusted weights.
:math:`\mathrm{itype} = 3`
Gauss--Laguerre, with normal weights.
:math:`\mathrm{itype} = -3`
Gauss--Laguerre, with adjusted weights.
:math:`\mathrm{itype} = 4`
Gauss--Hermite, with normal weights.
:math:`\mathrm{itype} = -4`
Gauss--Hermite, with adjusted weights.
:math:`\mathrm{itype} = 5`
Rational Gauss, with normal weights.
:math:`\mathrm{itype} = -5`
Rational Gauss, with adjusted weights.
**a** : float
The parameter :math:`\mathrm{a}` which occurs in the quadrature formula
**b** : float
The parameter :math:`\mathrm{b}` which occurs in the quadrature formula
**c** : float
The parameter :math:`\mathrm{c}` which occurs in the quadrature formula
**d** : float
The parameter :math:`\mathrm{d}` which occurs in the quadrature formula
**n** : int
:math:`n`, the number of weights and abscissae to be returned. If :math:`\mathrm{itype} = -2` or :math:`-4` and :math:`\mathrm{c}\neq 0.0`, an odd value of :math:`\mathrm{n}` may raise problems (see :math:`\mathrm{errno}` = 6).
**Returns**
**weight** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
The :math:`\mathrm{n}` weights.
**abscis** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
The :math:`\mathrm{n}` abscissae.
.. _d01tc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`2`)
On entry, :math:`\mathrm{itype} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\left\lvert \mathrm{itype}\right\rvert < 6`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n} > 0`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{a}`, :math:`\mathrm{b}`, :math:`\mathrm{c}`, or :math:`\mathrm{d}` is not in the allowed range: :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle` :math:`\mathrm{c} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{d} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{itype} = \langle\mathit{\boldsymbol{value}}\rangle`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
The algorithm for computing eigenvalues of a tridiagonal matrix has failed to converge.
(`errno` :math:`4`)
One or more of the weights are larger than :math:`\textit{rmax}`, the largest floating point number on this computer (see :meth:`machine.real_largest <naginterfaces.library.machine.real_largest>`): :math:`\textit{rmax} = \langle\mathit{\boldsymbol{value}}\rangle`.
Possible solutions are to use a smaller value of :math:`n`; or, if using adjusted weights to change to normal weights.
(`errno` :math:`5`)
One or more of the weights are too small to be distinguished from zero on this machine.
The underflowing weights are returned as zero, which may be a usable approximation.
Possible solutions are to use a smaller value of :math:`n`; or, if using normal weights, to change to adjusted weights.
(`errno` :math:`6`)
The contribution of the central abscissa to the summation is indeterminate.
.. _d01tc-py2-py-notes:
**Notes**
``dim1_gauss_wgen`` returns the weights :math:`w_i` and abscissae :math:`x_i` for use in the summation
.. math::
S = \sum_{{i = 1}}^nw_if\left(x_i\right)\text{,}
which approximates a definite integral (see Davis and Rabinowitz (1975) and Stroud and Secrest (1966)).
The following types are provided:
(a) Gauss--Legendre
.. math::
S\simeq \int_a^bf\left(x\right){dx}\text{, exact for }f\left(x\right) = P_{{2n-1}}\left(x\right)\text{.}
`Constraint:` :math:`b > a`.
(#) Gauss--Jacobi
normal weights:
.. math::
S\simeq \int_a^b\left(b-x\right)^c\left(x-a\right)^df\left(x\right){dx}\text{, exact for }f\left(x\right) = P_{{2n-1}}\left(x\right)\text{,}
adjusted weights:
.. math::
S\simeq \int_a^bf\left(x\right){dx}\text{, exact for }f\left(x\right) = \left(b-x\right)^c\left(x-a\right)^dP_{{2n-1}}\left(x\right)\text{.}
`Constraint:` :math:`c > -1`, :math:`d > -1`, :math:`b > a`.
(#) Exponential Gauss
normal weights:
.. math::
S\simeq \int_a^b\left\lvert x-\frac{{a+b}}{2}\right\rvert^cf\left(x\right){dx}\text{, exact for }f\left(x\right) = P_{{2n-1}}\left(x\right)\text{,}
adjusted weights:
.. math::
S\simeq \int_a^bf\left(x\right){dx}\text{, exact for }f\left(x\right) = \left\lvert x-\frac{{a+b}}{2}\right\rvert^cP_{{2n-1}}\left(x\right)\text{.}
`Constraint:` :math:`c > -1`, :math:`b > a`.
(#) Gauss--Laguerre
normal weights:
.. math::
\begin{array}{ll}S&\simeq \int_a^{\infty }\left\lvert x-a\right\rvert^ce^{{-bx}}f\left(x\right){dx}\quad \text{ }\quad \left(b > 0\right)\text{,}\\&\\&\simeq \int_{{-\infty }}^a\left\lvert x-a\right\rvert^ce^{{-bx}}f\left(x\right){dx}\quad \text{ }\quad \left(b < 0\right)\text{, exact for }f\left(x\right) = P_{{2n-1}}\left(x\right)\text{,}\end{array}
adjusted weights:
.. math::
\begin{array}{ll}S&\simeq \int_a^{\infty } f\left(x\right) {dx}\quad \text{ }\quad \left(b > 0\right)\text{,}\\&\\&\simeq \int_{{-\infty }}^a f\left(x\right) {dx}\quad \text{ }\quad \left(b < 0\right)\text{, exact for }f\left(x\right) = \left\lvert x-a\right\rvert^ce^{{-bx}}P_{{2n-1}}\left(x\right)\text{.}\end{array}
`Constraint:` :math:`c > -1`, :math:`b\neq 0`.
(#) Gauss--Hermite
normal weights:
.. math::
S\simeq \int_{{-\infty }}^{{+\infty }}\left\lvert x-a\right\rvert^ce^{{-b\left(x-a\right)^2}}f\left(x\right){dx}\text{, exact for }f\left(x\right) = P_{{2n-1}}\left(x\right)\text{,}
adjusted weights:
.. math::
S\simeq \int_{{-\infty }}^{{+\infty }}f\left(x\right){dx}\text{, exact for }f\left(x\right) = \left\lvert x-a\right\rvert^ce^{{-b\left(x-a\right)^2}}P_{{2n-1}}\left(x\right)\text{.}
`Constraint:` :math:`c > -1`, :math:`b > 0`.
(#) Rational Gauss
normal weights:
.. math::
\begin{array}{ll}S&\simeq \int_a^{\infty }\frac{\left\lvert x-a\right\rvert^c}{\left\lvert x+b\right\rvert^d}f\left(x\right){dx}\quad \text{ }\quad \left(a+b > 0\right)\text{,}\\&\\&\simeq \int_{{-\infty }}^a\frac{\left\lvert x-a\right\rvert^c}{\left\lvert x+b\right\rvert^d}f\left(x\right){dx}\quad \text{ }\quad \left(a+b < 0\right)\text{, exact for }f\left(x\right) = P_{{2n-1}} \left(\frac{1}{{x+b}}\right) \text{,}\end{array}
adjusted weights:
.. math::
\begin{array}{ll}S&\simeq \int_a^{\infty } f\left(x\right) {dx}\quad \text{ }\quad \left(a+b > 0\right)\text{,}\\&\\&\simeq \int_{{-\infty }}^a f\left(x\right) {dx}\quad \text{ }\quad \left(a+b < 0\right)\text{, exact for }f\left(x\right) = \frac{\left\lvert x-a\right\rvert^c}{\left\lvert x+b\right\rvert^d} P_{{2n-1}} \left(\frac{1}{{x+b}}\right) \text{.}\end{array}
`Constraint:` :math:`c > -1`, :math:`d > c+1`, :math:`a+b\neq 0`.
In the above formulae, :math:`P_{{2n-1}}\left(x\right)` stands for any polynomial of degree :math:`2n-1` or less in :math:`x`.
The method used to calculate the abscissae involves finding the eigenvalues of the appropriate tridiagonal matrix (see Golub and Welsch (1969)).
The weights are then determined by the formula
.. math::
w_i = \left\{\sum_{{j = 0}}^{{n-1}}P_j^*\left(x_i\right)^2\right\}^{-1}\text{,}
where :math:`P_j^*\left(x\right)` is the :math:`j`\ th orthogonal polynomial with respect to the weight function over the appropriate interval.
The weights and abscissae produced by ``dim1_gauss_wgen`` may be passed to :meth:`md_gauss`, which will evaluate the summations in one or more dimensions.
.. _d01tc-py2-py-references:
**References**
Davis, P J and Rabinowitz, P, 1975, `Methods of Numerical Integration`, Academic Press
Golub, G H and Welsch, J H, 1969, `Calculation of Gauss quadrature rules`, Math. Comput. (23), 221--230
Stroud, A H and Secrest, D, 1966, `Gaussian Quadrature Formulas`, Prentice--Hall
"""
raise NotImplementedError
[docs]def dim1_gauss_wrec(a, b, c, muzero):
r"""
``dim1_gauss_wrec`` computes the weights and abscissae of a Gaussian quadrature rule using the method of Golub and Welsch.
.. _d01td-py2-py-doc:
For full information please refer to the NAG Library document for d01td
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01tdf.html
.. _d01td-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{a}` contains the coefficients :math:`a\left(j\right)`.
**b** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{b}` contains the coefficients :math:`b\left(j\right)`.
**c** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{c}` contains the coefficients :math:`c\left(j\right)`.
**muzero** : float
:math:`\mathrm{muzero}` contains the definite integral of the weight function for the interval of interest.
**Returns**
**b** : float, ndarray, shape :math:`\left(n\right)`
Elements of :math:`\mathrm{b}` are altered to make the underlying eigenvalue problem symmetric.
**c** : float, ndarray, shape :math:`\left(n\right)`
Elements of :math:`\mathrm{c}` are altered to make the underlying eigenvalue problem symmetric.
**weight** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{weight}[j-1]` contains the weight corresponding to the :math:`j`\ th abscissa.
**abscis** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{abscis}[j-1]` the :math:`j`\ th abscissa.
.. _d01td-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
The number of weights and abscissae requested (:math:`\textit{n}`) is less than :math:`1`: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`4`)
Unexpected failure in eigenvalue computation. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`5`)
The algorithm failed to converge. The :math:`i`\ th diagonal was not zero: :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _d01td-py2-py-notes:
**Notes**
A tri-diagonal system of equations is formed from the coefficients of an underlying three-term recurrence formula:
.. math::
p\left(j\right)\left(x\right) = \left(a\left(j\right)x+b\left(j\right)\right)p\left(j-1\right)\left(x\right)-c\left(j\right)p\left(j-2\right)\left(x\right)
for a set of othogonal polynomials :math:`p\left(j\right)` induced by the quadrature.
This is described in greater detail in `the D01 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01intro.html>`__.
The user is required to specify the three-term recurrence and the value of the integral of the chosen weight function over the chosen interval.
As described in Golub and Welsch (1969) the abscissae are computed from the eigenvalues of this matrix and the weights from the first component of the eigenvectors.
LAPACK functions are used for the linear algebra to speed up computation.
.. _d01td-py2-py-references:
**References**
Golub, G H and Welsch, J H, 1969, `Calculation of Gauss quadrature rules`, Math. Comput. (23), 221--230
"""
raise NotImplementedError
[docs]def dim1_gauss_recm(n, mu):
r"""
Given the :math:`2n+l` moments of the weight function, ``dim1_gauss_recm`` generates the recursion coefficients needed by :meth:`dim1_gauss_wrec` to calculate a Gaussian quadrature rule.
.. _d01te-py2-py-doc:
For full information please refer to the NAG Library document for d01te
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01tef.html
.. _d01te-py2-py-parameters:
**Parameters**
**n** : int
:math:`n`, the number of weights and abscissae required.
**mu** : float, array-like, shape :math:`\left(2\times \mathrm{n}+1\right)`
:math:`\mathrm{mu}[i]` must contain the value of the moment with respect to :math:`x^i` i.e., :math:`\int w\left(x\right)x^{\textit{i}}dx`, for :math:`\textit{i} = 0,1,\ldots,{2n}`.
**Returns**
**a** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
Values helping define the three term recurrence used by :meth:`dim1_gauss_wrec`.
**b** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
Values helping define the three term recurrence used by :meth:`dim1_gauss_wrec`.
**c** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
Values helping define the three term recurrence used by :meth:`dim1_gauss_wrec`.
.. _d01te-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
The number of weights and abscissae requested (:math:`\mathrm{n}`) is less than :math:`1`: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
The problem is too ill conditioned, it breaks down at row :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
.. _d01te-py2-py-notes:
**Notes**
``dim1_gauss_recm`` should only be used if the three-term recurrence cannot be determined analytically.
A system of equations are formed, using the moments provided.
This set of equations becomes ill-conditioned for moderate values of :math:`n`, the number of abscissae and weights required.
In most implementations quadruple precision calculation is used to maintain as much accuracy as possible.
.. _d01te-py2-py-references:
**References**
Golub, G H and Welsch, J H, 1969, `Calculation of Gauss quadrature rules`, Math. Comput. (23), 221--230
"""
raise NotImplementedError
[docs]def dim1_gauss_vec(key, a, b, n, f, data=None):
r"""
``dim1_gauss_vec`` computes an estimate of the definite integral of a function of known analytical form, using a Gaussian quadrature formula with a specified number of abscissae.
Formulae are provided for a finite interval (Gauss--Legendre), a semi-infinite interval (Gauss--Laguerre, rational Gauss), and an infinite interval (Gauss--Hermite).
.. _d01ua-py2-py-doc:
For full information please refer to the NAG Library document for d01ua
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01uaf.html
.. _d01ua-py2-py-parameters:
**Parameters**
**key** : int
Indicates the quadrature formula.
:math:`\mathrm{key} = 0`
Gauss--Legendre quadrature on a finite interval, using normal weights.
:math:`\mathrm{key} = 3`
Gauss--Laguerre quadrature on a semi-infinite interval, using normal weights.
:math:`\mathrm{key} = -3`
Gauss--Laguerre quadrature on a semi-infinite interval, using adjusted weights.
:math:`\mathrm{key} = 4`
Gauss--Hermite quadrature on an infinite interval, using normal weights.
:math:`\mathrm{key} = -4`
Gauss--Hermite quadrature on an infinite interval, using adjusted weights.
:math:`\mathrm{key} = -5`
Rational Gauss quadrature on a semi-infinite interval, using adjusted weights.
**a** : float
The quantities :math:`a` and :math:`b` as described in the appropriate subsection of :ref:`Notes <d01ua-py2-py-notes>`.
**b** : float
The quantities :math:`a` and :math:`b` as described in the appropriate subsection of :ref:`Notes <d01ua-py2-py-notes>`.
**n** : int
:math:`n`, the number of abscissae to be used.
**f** : callable (fv, iflag) = f(x, iflag, data=None)
:math:`\mathrm{f}` must return the value of the integrand :math:`f`, or the normalized integrand :math:`g`, at a set of points.
**Parameters**
**x** : float, ndarray, shape :math:`\left(\textit{nx}\right)`
The abscissae, :math:`x_i`, for :math:`\textit{i} = 1,2,\ldots,n_x` at which function values are required.
**iflag** : int
:math:`\mathrm{iflag} = 0`.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fv** : float, array-like, shape :math:`\left(\textit{nx}\right)`
If adjusted weights are used, the values of the integrand :math:`f`. :math:`\mathrm{fv}[\textit{i}-1] = f\left(x_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
Otherwise the values of the normalized integrand :math:`g`. :math:`\mathrm{fv}[\textit{i}-1] = g\left(x_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
**iflag** : int
Set :math:`\mathrm{iflag} < 0` if you wish to force an immediate exit from ``dim1_gauss_vec`` with :math:`\mathrm{errno}` = -1.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**dinest** : float
The estimate of the definite integral.
.. _d01ua-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`11`)
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{key} = 0`, :math:`3`, :math:`-3`, :math:`4`, :math:`-4` or :math:`-5`.
(`errno` :math:`12`)
The value of :math:`\mathrm{a}` and/or :math:`\mathrm{b}` is invalid.
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
On entry, :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\left\lvert \mathrm{b}\right\rvert > 0.0`.
(`errno` :math:`12`)
The value of :math:`\mathrm{a}` and/or :math:`\mathrm{b}` is invalid.
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
On entry, :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{b} > 0.0`.
(`errno` :math:`12`)
The value of :math:`\mathrm{a}` and/or :math:`\mathrm{b}` is invalid.
On entry, :math:`\mathrm{key} = \langle\mathit{\boldsymbol{value}}\rangle`.
On entry, :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\left\lvert \mathrm{a}+\mathrm{b}\right\rvert > 0.0`.
(`errno` :math:`14`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n} > 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`-1`)
Exit requested from :math:`\mathrm{f}` with :math:`\mathrm{iflag} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
The :math:`n`-point rule is not among those stored.
On entry: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
:math:`n`-point rule used: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Underflow occurred in calculation of normal weights.
Reduce :math:`\mathrm{n}` or use adjusted weights: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
No nonzero weights were generated for the provided parameters.
.. _d01ua-py2-py-notes:
**Notes**
**General**
``dim1_gauss_vec`` evaluates an estimate of the definite integral of a function :math:`f\left(x\right)`, over a finite or infinite range, by :math:`n`-point Gaussian quadrature (see Davis and Rabinowitz (1975), Fröberg (1970), Ralston (1965) and Stroud and Secrest (1966)).
The integral is approximated by a summation of the product of a set of weights and a set of function evaluations at a corresponding set of abscissae :math:`x_i`.
For adjusted weights, the function values correspond to the values of the integrand :math:`f`, and hence the sum will be
.. math::
\sum_{{i = 1}}^nw_if\left(x_i\right)
where the :math:`w_i` are called the weights, and the :math:`x_i` the abscissae.
A selection of values of :math:`n` is available. (See :ref:`Parameters <d01ua-py2-py-parameters>`.)
Where applicable, normal weights may instead be used, in which case the corresponding weight function :math:`\omega` is factored out of the integrand as :math:`f\left(x\right) = \omega \left(x\right)g\left(x\right)` and hence the sum will be
.. math::
\sum_{-1}^{n}{\bar{w}_i}g\left(x\right)\text{,}
where the normal weights :math:`\bar{w}_i = w_i\omega \left(x_i\right)` are computed internally.
``dim1_gauss_vec`` uses a vectorized :math:`\mathrm{f}` to evaluate the integrand or normalized integrand at a set of abscissae, :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n_x`.
If adjusted weights are used, the integrand :math:`f\left(x_i\right)` must be evaluated otherwise the normalized integrand :math:`g\left(x_i\right)` must be evaluated.
**Both Limits Finite**
.. math::
\int_a^bf\left(x\right){dx}\text{.}
The Gauss--Legendre weights and abscissae are used, and the formula is exact for any function of the form:
.. math::
f\left(x\right) = \sum_{{i = 0}}^{{2n-1}}c_ix^i\text{.}
The formula is appropriate for functions which can be well approximated by such a polynomial over :math:`\left[a, b\right]`.
It is inappropriate for functions with algebraic singularities at one or both ends of the interval, such as :math:`\left(1+x\right)^{{-1/2}}` on :math:`\left[-1, 1\right]`.
**One Limit Infinite**
.. math::
\int_a^{\infty }f\left(x\right){dx}\quad \text{ or }\quad \int_{{-\infty }}^af\left(x\right){dx}\text{.}
Two quadrature formulae are available for these integrals.
(a) The Gauss--Laguerre formula is exact for any function of the form:
.. math::
f\left(x\right) = e^{{-bx}}\sum_{{i = 0}}^{{2n-1}}c_ix^i\text{.}
This formula is appropriate for functions decaying exponentially at infinity; the argument :math:`b` should be chosen if possible to match the decay rate of the function.
If the adjusted weights are selected, the complete integrand :math:`f\left(x\right)` should be provided through :math:`\mathrm{f}`.
If the normal form is selected, the contribution of :math:`e^{{-bx}}` is accounted for internally, and :math:`\mathrm{f}` should only return :math:`g\left(x\right)`, where :math:`f\left(x\right) = e^{{-bx}}g\left(x\right)`.
If :math:`b < 0` is supplied, the interval of integration will be :math:`\left[a, \infty \right)`.
Otherwise if :math:`b > 0` is supplied, the interval of integration will be :math:`\left({-\infty }, a\right]`.
(#) The rational Gauss formula is exact for any function of the form:
.. math::
f\left(x\right) = \sum_{{i = 2}}^{{2n+1}}\frac{c_i}{\left(x+b\right)^i} = \frac{{\sum_{{i = 0}}^{{2n-1}}c_{{2n+1-i}}\left(x+b\right)^i}}{\left(x+b\right)^{{2n+1}}}\text{.}
This formula is likely to be more accurate for functions having only an inverse power rate of decay for large :math:`x`.
Here the choice of a suitable value of :math:`b` may be more difficult; unfortunately a poor choice of :math:`b` can make a large difference to the accuracy of the computed integral.
Only the adjusted form of the rational Gauss formula is available, and as such, the complete integrand :math:`f\left(x\right)` must be supplied in :math:`\mathrm{f}`.
If :math:`a+b < 0`, the interval of integration will be :math:`\left[a, \infty \right)`.
Otherwise if :math:`a+b > 0`, the interval of integration will be :math:`\left({-\infty }, a\right]`.
**Both Limits Infinite**
.. math::
\int_{{-\infty }}^{{+\infty }}f\left(x\right){dx}\text{.}
The Gauss--Hermite weights and abscissae are used, and the formula is exact for any function of the form:
.. math::
f\left(x\right) = e^{{-b\left(x-a\right)^2}}\sum_{{i = 0}}^{{2n-1}}c_ix^i\text{,}
where :math:`b > 0`.
Again, for general functions not of this exact form, the argument :math:`b` should be chosen to match if possible the decay rate at :math:`\text{}\pm \infty`.
If the adjusted weights are selected, the complete integrand :math:`f\left(x\right)` should be provided through :math:`\mathrm{f}`.
If the normal form is selected, the contribution of :math:`e^{{-b\left(x-a\right)^2}}` is accounted for internally, and :math:`\mathrm{f}` should only return :math:`g\left(x\right)`, where :math:`f\left(x\right) = e^{{-b\left(x-a\right)^2}}g\left(x\right)`.
.. _d01ua-py2-py-references:
**References**
Davis, P J and Rabinowitz, P, 1975, `Methods of Numerical Integration`, Academic Press
Fröberg, C E, 1970, `Introduction to Numerical Analysis`, Addison--Wesley
Ralston, A, 1965, `A First Course in Numerical Analysis`, pp. 87--90, McGraw--Hill
Stroud, A H and Secrest, D, 1966, `Gaussian Quadrature Formulas`, Prentice--Hall
"""
raise NotImplementedError
[docs]def dim1_inf_exp_wt(f, n, data=None):
r"""
``dim1_inf_exp_wt`` returns the Gaussian quadrature approximation for the specific problem :math:`\int_0^{\infty }\mathrm{exp}\left({-x}^2\right)f\left(x\right)dx`.
The degrees of precision catered for are: :math:`1`, :math:`3`, :math:`5`, :math:`7`, :math:`9`, :math:`19`, :math:`29`, :math:`39` and :math:`49`, corresponding to values of :math:`n = 1`, :math:`2`, :math:`3`, :math:`4`, :math:`5`, :math:`10`, :math:`15`, :math:`20` and :math:`25`, where :math:`n` is the number of weights.
.. _d01ub-py2-py-doc:
For full information please refer to the NAG Library document for d01ub
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01ubf.html
.. _d01ub-py2-py-parameters:
**Parameters**
**f** : callable (fv, istop) = f(x, istop, data=None)
:math:`\mathrm{f}` must return the integrand function values :math:`f\left(x_i\right)` for the given :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{n}`.
**Parameters**
**x** : float, ndarray, shape :math:`\left(n\right)`
The points at which the integrand function :math:`f` must be evaluated.
**istop** : int
:math:`\mathrm{istop} = 0`.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fv** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{fv}[\textit{i}-1]` must contain the value of the integrand :math:`f\left(x_i\right)` evaluated at the point :math:`\mathrm{x}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{n}`.
**istop** : int
You may set :math:`\mathrm{istop}` to a negative number if at any time it is impossible to evaluate the function :math:`f\left(x\right)`. In this case ``dim1_inf_exp_wt`` halts with :math:`\textit{errno}` set to the value of :math:`\mathrm{istop}` and the value returned in :math:`\mathrm{ans}` will be that of a non-signalling NaN.
**n** : int
:math:`\mathrm{n}` specifies the number of weights and abscissae to be used.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**ans** : float
If no exception or warning is raised, :math:`\mathrm{ans}` contains an approximation to the integral. Otherwise, :math:`\mathrm{ans}` will be a non-signalling NaN.
.. _d01ub-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`i < 0`)
The user has halted the calculation.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`1\leq \mathrm{n}\leq 25`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
:math:`\mathrm{n}` is not one of the allowed values.
.. _d01ub-py2-py-notes:
**Notes**
``dim1_inf_exp_wt`` uses the weights :math:`w_i` and the abscissae :math:`x_i` such that :math:`\int_0^{\infty }\mathrm{exp}\left({{-x}^2}\right)f\left(x\right)` is approximated by :math:`\sum_{1}^{n}{w_if\left(x_i\right)}` to maximum precision i.e., it is exact when :math:`f\left(x\right)` is a polynomial of degree :math:`2n-1`.
.. _d01ub-py2-py-references:
**References**
Golub, G H and Welsch, J H, 1969, `Calculation of Gauss quadrature rules`, Math. Comput. (23), 221--230
"""
raise NotImplementedError
[docs]def opt_set(optstr, comm):
r"""
``opt_set`` either initializes or resets the option arrays or sets a single option for supported problem solving functions in submodule ``quad``.
.. _d01zk-py2-py-doc:
For full information please refer to the NAG Library document for d01zk
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01zkf.html
.. _d01zk-py2-py-parameters:
**Parameters**
**optstr** : str
A string identifying the option to be set.
Initialize = :math:`\textit{function name}`
Initialize the option arrays :math:`\mathrm{comm}`\ ['iopts'] and :math:`\mathrm{comm}`\ ['opts'] for use with function :math:`\textit{function name}`, where :math:`\textit{function name}` is the name associated with the function of interest.
Defaults
Resets all options to their default values.
:math:`\textit{option} = \textit{optval}`
See :ref:`Other Parameters for md_sgq_multi_vec <d01es-py2-py-other_params>` and :ref:`Other Parameters for dim1_gen_vec_multi_rcomm <d01ra-py2-py-other_params>` for details of valid values for :math:`\textit{option}` and :math:`\textit{optval}`. The equals sign (:math:`=`) delimiter must be used to separate the :math:`\textit{option}` from its :math:`\textit{optval}` value.
:math:`\mathrm{optstr}` is case insensitive.
Each token in the :math:`\textit{option}` and :math:`\textit{optval}` component must be separated by at least one space.
**comm** : dict, communication object, modified in place
Communication structure.
`On initial entry`: need not be set.
.. _d01zk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`14`)
On entry, attempting to initialize the option arrays but specified function name was not valid: :math:`\text{name} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`21`)
On entry, either the option arrays have not been initialized or they have been corrupted.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`11`)
On entry, the option in :math:`\mathrm{optstr}` was not recognized: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`12`)
On entry, the expected delimiter ':math:`=`' was not found in :math:`\mathrm{optstr}`: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`13`)
On entry, could not convert the specified :math:`\textit{optval}` to an integer: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`13`)
On entry, could not convert the specified :math:`\textit{optval}` to a real: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`15`)
On entry, the :math:`\textit{optval}` supplied for the integer option is not valid.
:math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`16`)
On entry, the :math:`\textit{optval}` supplied for the real option is not valid.
:math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`17`)
On entry, the :math:`\textit{optval}` supplied for the character option is not valid.
:math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _d01zk-py2-py-notes:
**Notes**
``opt_set`` has three purposes: to initialize option arrays; to reset all options to their default values; or to set a single option to a user-supplied value.
Options and their values are, in general, presented as a character string, :math:`\mathrm{optstr}`, of the form ':math:`\textit{option} = \textit{optval}`'; alphabetic characters can be supplied in either upper or lower case.
Both :math:`\textit{option}` and :math:`\textit{optval}` may consist of one or more tokens separated by white space.
The tokens that comprise :math:`\textit{optval}` will normally be either an integer, real or character value as defined in the description of the specific optional argument.
In addition all options can take an :math:`\textit{optval}` DEFAULT which resets the option to its default value.
It is imperative that option arrays are initialized before any options are set, before the relevant problem solving function is called and before any options are queried using :meth:`opt_get`.
The available option names and their corresponding valid values are given in :ref:`Other Parameters for md_sgq_multi_vec <d01es-py2-py-other_params>` and :ref:`Other Parameters for dim1_gen_vec_multi_rcomm <d01ra-py2-py-other_params>`.
"""
raise NotImplementedError
[docs]def opt_get(optstr, comm):
r"""
``opt_get`` is used to query the current value associated with an option for :meth:`md_sgq_multi_vec` and :meth:`dim1_gen_vec_multi_rcomm`.
.. _d01zl-py2-py-doc:
For full information please refer to the NAG Library document for d01zl
https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01zlf.html
.. _d01zl-py2-py-parameters:
**Parameters**
**optstr** : str
A string identifying the option whose current value is required. See :ref:`Other Parameters for md_sgq_multi_vec <d01es-py2-py-other_params>` and :ref:`Other Parameters for dim1_gen_vec_multi_rcomm <d01ra-py2-py-other_params>` for information on valid options. In addition, the following is a valid option:
Identify
In which case ``opt_get`` returns the :math:`6` character function name supplied to :meth:`opt_set` when the option arrays :math:`\mathrm{comm}`\ ['iopts'] and :math:`\mathrm{comm}`\ ['opts'] were initialized.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`opt_set`.
**Returns**
**optvalue** : dict
The option-value ``dict``, with the following keys:
``'value'`` : float, int or str
The value of the requested option.
``'annotation'`` : None or str
Possible additional information about the option value.
.. _d01zl-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`61`)
The arrays :math:`\mathrm{comm}`\ ['iopts'] and :math:`\mathrm{comm}`\ ['opts'] have either not been initialized, have become corrupted, or are not compatible with this option setting function.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`11`)
On entry, the option in :math:`\mathrm{optstr}` was not recognized: :math:`\mathrm{optstr} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`41`)
On entry, :math:`\mathrm{optstr}` indicates a character option, but :math:`\textit{cvalue}` is too short to hold the stored value. The returned value will be truncated.
.. _d01zl-py2-py-notes:
**Notes**
``opt_get`` is used to query the current value associated with options.
It is necessary to initialize option arrays, :math:`\mathrm{comm}`\ ['iopts'] and :math:`\mathrm{comm}`\ ['opts'], using :meth:`opt_set` before any options are queried.
Information on option names and whether these options are real, integer or character can be found in :ref:`Other Parameters for md_sgq_multi_vec <d01es-py2-py-other_params>` and :ref:`Other Parameters for dim1_gen_vec_multi_rcomm <d01ra-py2-py-other_params>`.
"""
raise NotImplementedError
