# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.2 `interp` Chapter.
``interp`` - Interpolation
This module is concerned with the interpolation of a function of one or more variables.
When provided with the value of the function (and possibly one or more of its lowest-order derivatives) at each of a number of values of the variable(s), the NAG Library functions provide either an interpolating function or an interpolated value.
For some of the interpolating functions, there are supporting NAG Library functions to evaluate, differentiate or integrate them.
Functionality Index
-------------------
**Derivative**
of interpolant
from :meth:`dim1_monotonic`: :meth:`dim1_monotonic_deriv`
from :meth:`dim2_scat_shep`: :meth:`dim2_scat_shep_eval`
from :meth:`dim3_scat_shep`: :meth:`dim3_scat_shep_eval`
from :meth:`dim4_scat_shep`: :meth:`dim4_scat_shep_eval`
from :meth:`dim5_scat_shep`: :meth:`dim5_scat_shep_eval`
from :meth:`dimn_scat_shep`: :meth:`dimn_scat_shep_eval`
**Evaluation**
of interpolant
from :meth:`dim1_monotonic`: :meth:`dim1_monotonic_eval`
from :meth:`dim1_ratnl`: :meth:`dim1_ratnl_eval`
from :meth:`dim2_scat`: :meth:`dim2_scat_eval`
from :meth:`dim2_scat_shep`: :meth:`dim2_scat_shep_eval`
from :meth:`dim3_scat_shep`: :meth:`dim3_scat_shep_eval`
from :meth:`dim4_scat_shep`: :meth:`dim4_scat_shep_eval`
from :meth:`dim5_scat_shep`: :meth:`dim5_scat_shep_eval`
from :meth:`dimn_scat_shep`: :meth:`dimn_scat_shep_eval`
from triangulation from :meth:`dim2_triangulate`: :meth:`dim2_triang_bary_eval`
using variables computed by :meth:`dim1_monconv_disc`: :meth:`dim1_monconv_eval`
**Extrapolation**
one variable
monotonic convex: :meth:`dim1_monconv_disc`
piecewise cubic: :meth:`dim1_monotonic`
polynomial
data with or without derivatives: :meth:`dim1_cheb`
general data: :meth:`dim1_aitken`
rational function: :meth:`dim1_ratnl`
Integration (definite) of interpolant from :meth:`dim1_monotonic`: :meth:`dim1_monotonic_intg`
**Interpolated values**
:math:`d` variables
from interpolant from :meth:`dimn_scat_shep`: :meth:`dimn_scat_shep_eval`
modified Shepard method, Linear or Cubic: :meth:`dimn_grid`
five variables
from interpolant from :meth:`dim5_scat_shep`: :meth:`dim5_scat_shep_eval`
four variables
from interpolant from :meth:`dim4_scat_shep`: :meth:`dim4_scat_shep_eval`
one variable
from interpolant from :meth:`dim1_monotonic`: :meth:`dim1_monotonic_eval`
from interpolant from :meth:`dim1_monotonic` (including derivative): :meth:`dim1_monotonic_deriv`
from polynomial
equally spaced data: :meth:`dim1_everett`
general data: :meth:`dim1_aitken`
from rational function: :meth:`dim1_ratnl_eval`
using variables computed by :meth:`dim1_monconv_disc`: :meth:`dim1_monconv_eval`
three variables
from interpolant from :meth:`dim3_scat_shep`: :meth:`dim3_scat_shep_eval`
two variables
barycentric, from triangulation from :meth:`dim2_triangulate`: :meth:`dim2_triang_bary_eval`
from interpolant from :meth:`dim2_scat`: :meth:`dim2_scat_eval`
from interpolant from :meth:`dim2_scat_shep`: :meth:`dim2_scat_shep_eval`
**Interpolating function**
:math:`d` variables
modified Shepard method: :meth:`dimn_scat_shep`
five variables
modified Shepard method: :meth:`dim5_scat_shep`
four variables
modified Shepard method: :meth:`dim4_scat_shep`
one variable
cubic spline: :meth:`dim1_spline`
monotonic convex piecewise polynomial: :meth:`dim1_monconv_disc`
other piecewise polynomial: :meth:`dim1_monotonic`
polynomial
data with or without derivatives: :meth:`dim1_cheb`
rational function: :meth:`dim1_ratnl`
three variables
modified Shepard method: :meth:`dim3_scat_shep`
two variables
bicubic spline: :meth:`dim2_spline_grid`
modified Shepard method: :meth:`dim2_scat_shep`
other piecewise polynomial: :meth:`dim2_scat`
triangulation: :meth:`dim2_triangulate`
For full information please refer to the NAG Library document
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01intro.html
"""
# NAG Copyright 2017-2024.
[docs]def dim1_aitken(a, b, x):
r"""
``dim1_aitken`` interpolates a function of one variable at a given point :math:`x` from a table of function values :math:`y_i` evaluated at equidistant or non-equidistant points :math:`x_i`, for :math:`\textit{i} = 1,2,\ldots,n+1`, using Aitken's technique of successive linear interpolations.
.. _e01aa-py2-py-doc:
For full information please refer to the NAG Library document for e01aa
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01aaf.html
.. _e01aa-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n+1\right)`
:math:`\mathrm{a}[\textit{i}-1]` must contain the :math:`x`-component of the :math:`\textit{i}`\ th data point, :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n+1`.
**b** : float, array-like, shape :math:`\left(n+1\right)`
:math:`\mathrm{b}[\textit{i}-1]` must contain the :math:`y`-component (function value) of the :math:`\textit{i}`\ th data point, :math:`y_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n+1`.
**x** : float
The point :math:`x` at which the interpolation is required. Note that :math:`\mathrm{x}` may lie outside the interval defined by the minimum and maximum values in :math:`\mathrm{a}`, in which case an extrapolated value will be computed; extrapolated results should be treated with considerable caution since there is no information on the behaviour of the function outside the defined interval.
**Returns**
**a** : float, ndarray, shape :math:`\left(n+1\right)`
:math:`\mathrm{a}[\textit{i}-1]` contains the value :math:`x_{\textit{i}}-x`, for :math:`\textit{i} = 1,2,\ldots,n+1`.
**b** : float, ndarray, shape :math:`\left(n+1\right)`
The contents of :math:`\mathrm{b}` are unspecified.
**c** : float, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)`
:math:`\mathrm{c}[0],\ldots,\mathrm{c}[n-1]` contain the first set of linear interpolations,
:math:`\mathrm{c}[n],\ldots,\mathrm{c}[2\times n-2]` contain the second set of linear interpolations,
:math:`\mathrm{c}[2n-1],\ldots,\mathrm{c}[3\times n-4]` contain the third set of linear interpolations,
:math:`\vdots`
:math:`\mathrm{c}[{n\times \left(n+1\right)/2}-1]` contains the interpolated function value at the point :math:`x`.
.. _e01aa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`6`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n > 0`.
.. _e01aa-py2-py-notes:
**Notes**
``dim1_aitken`` interpolates a function of one variable at a given point :math:`x` from a table of values :math:`x_i` and :math:`y_i`, for :math:`i = 1,2,\ldots,n+1` using Aitken's method (see Fröberg (1970)).
The intermediate values of linear interpolations are stored to enable an estimate of the accuracy of the results to be made.
.. _e01aa-py2-py-references:
**References**
Fröberg, C E, 1970, `Introduction to Numerical Analysis`, Addison--Wesley
"""
raise NotImplementedError
[docs]def dim1_everett(p, a):
r"""
``dim1_everett`` interpolates a function of one variable at a given point :math:`x` from a table of function values evaluated at equidistant points, using Everett's formula.
.. _e01ab-py2-py-doc:
For full information please refer to the NAG Library document for e01ab
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01abf.html
.. _e01ab-py2-py-parameters:
**Parameters**
**p** : float
The point :math:`p` at which the interpolated function value is required, i.e., :math:`p = \left(x-x_0\right)/h` with :math:`{-1.0} < p < 1.0`.
**a** : float, array-like, shape :math:`\left(2\times n\right)`
:math:`\mathrm{a}[\textit{i}-1]` must be set to the function value :math:`y_{{\textit{i}-n}}`, for :math:`\textit{i} = 1,2,\ldots,2n`.
**Returns**
**a** : float, ndarray, shape :math:`\left(2\times n\right)`
The contents of :math:`\mathrm{a}` are unspecified.
**g** : float, ndarray, shape :math:`\left(2\times n+1\right)`
The array contains
.. rst-class:: nag-rules-none nag-align-left
+------------------------+------------------------------------------------------------------------------+
|:math:`y_0` |in :math:`\mathrm{g}[0]` |
+------------------------+------------------------------------------------------------------------------+
|:math:`y_1` |in :math:`\mathrm{g}[1]` |
+------------------------+------------------------------------------------------------------------------+
|:math:`\delta^{{2r}}y_0`|in :math:`\mathrm{g}[2r]` |
+------------------------+------------------------------------------------------------------------------+
|:math:`\delta^{{2r}}y_1`|in :math:`\mathrm{g}[2\textit{r}+1]`, for :math:`\textit{r} = 1,2,\ldots,n-1`.|
+------------------------+------------------------------------------------------------------------------+
The interpolated function value :math:`y_p` is stored in :math:`\mathrm{g}[2n]`.
.. _e01ab-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{p}\leq 1.0`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{p} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{p}\geq {-1.0}`.
(`errno` :math:`2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
.. _e01ab-py2-py-notes:
**Notes**
``dim1_everett`` interpolates a function of one variable at a given point
.. math::
x = x_0+ph\text{,}
where :math:`-1\leq p\leq 1` and :math:`h` is the interval of differencing, from a table of values :math:`x_m = x_0+mh` and :math:`y_m` where :math:`m = -\left(n-1\right),-\left(n-2\right),\ldots,-1,0,1,\ldots,n`.
The formula used is that of Fröberg (1970), neglecting the remainder term:
.. math::
y_p = \sum_{{r = 0}}^{{n-1}}\left(\frac{{1-p+r}}{{2r+1}}\right)\delta^{{2r}}y_0+\sum_{{r = 0}}^{{n-1}}\left(\frac{{p+r}}{{2r+1}}\right)\delta^{{2r}}y_1\text{.}
The values of :math:`\delta^{{2r}}y_0` and :math:`\delta^{{2r}}y_1` are stored on exit from the function in addition to the interpolated function value :math:`y_p`.
.. _e01ab-py2-py-references:
**References**
Fröberg, C E, 1970, `Introduction to Numerical Analysis`, Addison--Wesley
"""
raise NotImplementedError
[docs]def dim1_cheb(xmin, xmax, x, y, ip, lwrk, liwrk, itmin=0, itmax=0):
r"""
``dim1_cheb`` constructs the Chebyshev series representation of a polynomial interpolant to a set of data which may contain derivative values.
.. _e01ae-py2-py-doc:
For full information please refer to the NAG Library document for e01ae
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01aef.html
.. _e01ae-py2-py-parameters:
**Parameters**
**xmin** : float
The lower and upper end points, respectively, of the interval :math:`\left[x_{\mathrm{min}}, x_{\mathrm{max}}\right]`. If they are not determined by your problem, it is recommended that they be set respectively to the smallest and largest values among the :math:`x_i`.
**xmax** : float
The lower and upper end points, respectively, of the interval :math:`\left[x_{\mathrm{min}}, x_{\mathrm{max}}\right]`. If they are not determined by your problem, it is recommended that they be set respectively to the smallest and largest values among the :math:`x_i`.
**x** : float, array-like, shape :math:`\left(m\right)`
The value of :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,m`. The :math:`\mathrm{x}[i-1]` need not be ordered.
**y** : float, array-like, shape :math:`\left(n\right)`
The given values of the dependent variable, and derivatives, as follows:
The first :math:`p_1+1` elements contain :math:`y_1,y_1^{\left(1\right)},\ldots,y_1^{\left(p_1\right)}` in that order.
The next :math:`p_2+1` elements contain :math:`y_2,y_2^{\left(1\right)},\ldots,y_2^{\left(p_2\right)}` in that order.
:math:`\quad \text{ }\quad \vdots`
The last :math:`p_m+1` elements contain :math:`y_m,y_m^{\left(1\right)},\ldots,y_m^{\left(p_m\right)}` in that order.
**ip** : int, array-like, shape :math:`\left(m\right)`
:math:`p_{\textit{i}}`, the order of the highest-order derivative whose value is given at :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,m`. If the value of :math:`y` only is given for some :math:`x_i` then the corresponding value of :math:`\mathrm{ip}[i-1]` must be zero.
**lwrk** : int
The dimension of the array :math:`\mathrm{wrk}`.
**liwrk** : int
The dimension of the array :math:`\mathrm{iwrk}`.
**itmin** : int, optional
Respectively the minimum and maximum number of iterations to be performed by the function (for full details see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01aef.html#fcomments4>`__). Setting :math:`\mathrm{itmin}` and/or :math:`\mathrm{itmax}` negative or zero invokes default value(s) of :math:`2` and/or :math:`10`, respectively.
The default values will be satisfactory for most problems, but occasionally significant improvement will result from using higher values.
**itmax** : int, optional
Respectively the minimum and maximum number of iterations to be performed by the function (for full details see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01aef.html#fcomments4>`__). Setting :math:`\mathrm{itmin}` and/or :math:`\mathrm{itmax}` negative or zero invokes default value(s) of :math:`2` and/or :math:`10`, respectively.
The default values will be satisfactory for most problems, but occasionally significant improvement will result from using higher values.
**Returns**
**a** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{a}[\textit{i}]` contains the coefficient :math:`a_{\textit{i}}` in the Chebyshev series representation of :math:`q\left(x\right)`, for :math:`\textit{i} = 0,\ldots,n-1`.
**wrk** : float, ndarray, shape :math:`\left(\mathrm{lwrk}\right)`
Used as workspace, but see also `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01aef.html#fcomments5>`__.
**iwrk** : int, ndarray, shape :math:`\left(\mathrm{liwrk}\right)`
Used as workspace, but see also `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01aef.html#fcomments5>`__.
.. _e01ae-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{liwrk}` is too small. :math:`\mathrm{liwrk} = \langle\mathit{\boldsymbol{value}}\rangle`. Minimum possible dimension: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{lwrk}` is too small. :math:`\mathrm{lwrk} = \langle\mathit{\boldsymbol{value}}\rangle`. Minimum possible dimension: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m+\mathrm{ip}[0]+\mathrm{ip}[1] + \cdots +\mathrm{ip}[m-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n = m+\mathrm{ip}[0]+\mathrm{ip}[1] + \cdots +\mathrm{ip}[m-1]`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{ip}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ip}[\textit{I}-1]\geq 0`.
(`errno` :math:`3`)
On entry, :math:`\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{x}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{x}[\textit{I}-1]\neq \mathrm{x}[\textit{J}-1]`.
(`errno` :math:`3`)
On entry, :math:`\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{xmin} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{xmax} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{xmin}\leq \mathrm{x}[\textit{I}-1]\leq \mathrm{xmax}`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{xmin} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{xmax} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{xmin} < \mathrm{xmax}`.
(`errno` :math:`5`)
The computation has been terminated because the iterative process appears to be diverging.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`4`)
Not all the performance indices are less than eight times the machine precision, although :math:`\mathrm{itmax}` iterations have been performed. A more accurate solution may possibly be obtained by increasing :math:`\mathrm{itmax}` and recalling the function.
.. _e01ae-py2-py-notes:
**Notes**
Let :math:`m` distinct values :math:`x_{\textit{i}}` of an independent variable :math:`x` be given, with :math:`x_{\mathrm{min}}\leq x_{\textit{i}}\leq x_{\mathrm{max}}`, for :math:`\textit{i} = 1,2,\ldots,m`.
For each value :math:`x_i`, suppose that the value :math:`y_i` of the dependent variable :math:`y` together with the first :math:`p_i` derivatives of :math:`y` with respect to :math:`x` are given.
Each :math:`p_i` must, therefore, be a non-negative integer, with the total number of interpolating conditions, :math:`n`, equal to :math:`m+\sum_{{i = 1}}^mp_i`.
``dim1_cheb`` calculates the unique polynomial :math:`q\left(x\right)` of degree :math:`n-1` (or less) which is such that :math:`q^{\left(\textit{k}\right)}\left(x_{\textit{i}}\right) = y_{\textit{i}}^{\left(\textit{k}\right)}`, for :math:`\textit{k} = 0,1,\ldots,p_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,m`.
Here :math:`q^{\left(0\right)}\left(x_i\right)` means :math:`q\left(x_i\right)`.
This polynomial is represented in Chebyshev series form in the normalized variable :math:`\bar{x}`, as follows:
.. math::
q\left(x\right) = \frac{1}{2}a_0T_0\left(\bar{x}\right)+a_1T_1\left(\bar{x}\right)+ \cdots +a_{{n-1}}T_{{n-1}}\left(\bar{x}\right)\text{,}
where
.. math::
\bar{x} = \frac{{2x-x_{\mathrm{min}}-x_{\mathrm{max}}}}{{x_{\mathrm{max}}-x_{\mathrm{min}}}}
so that :math:`-1\leq \bar{x}\leq 1` for :math:`x` in the interval :math:`x_{\mathrm{min}}` to :math:`x_{\mathrm{max}}`, and where :math:`T_i\left(\bar{x}\right)` is the Chebyshev polynomial of the first kind of degree :math:`i` with argument :math:`\bar{x}`.
(The polynomial interpolant can subsequently be evaluated for any value of :math:`x` in the given range by using :meth:`fit.dim1_cheb_eval2 <naginterfaces.library.fit.dim1_cheb_eval2>`.
Chebyshev series representations of the derivative(s) and integral(s) of :math:`q\left(x\right)` may be obtained by (repeated) use of :meth:`fit.dim1_cheb_deriv <naginterfaces.library.fit.dim1_cheb_deriv>` and :meth:`fit.dim1_cheb_integ <naginterfaces.library.fit.dim1_cheb_integ>`.)
The method used consists first of constructing a divided-difference table from the normalized :math:`\bar{x}` values and the given values of :math:`y` and its derivatives with respect to :math:`\bar{x}`.
The Newton form of :math:`q\left(x\right)` is then obtained from this table, as described in Huddleston (1974) and Krogh (1970), with the modification described in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01aef.html#fcomments2>`__.
The Newton form of the polynomial is then converted to Chebyshev series form as described in `Conversion to Chebyshev Form <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01aef.html#fcomments3>`__.
Since the errors incurred by these stages can be considerable, a form of iterative refinement is used to improve the solution.
This refinement is particularly useful when derivatives of rather high order are given in the data.
In reasonable examples, the refinement will usually terminate with a certain accuracy criterion satisfied by the polynomial (see `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01aef.html#accuracy>`__).
In more difficult examples, the criterion may not be satisfied and refinement will continue until the maximum number of iterations (as specified by the input argument :math:`\mathrm{itmax}`) is reached.
In extreme examples, the iterative process may diverge (even though the accuracy criterion is satisfied): if a certain divergence criterion is satisfied, the process terminates at once.
In all cases the function returns the 'best' polynomial achieved before termination.
For the definition of 'best' and details of iterative refinement and termination criteria, see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01aef.html#fcomments4>`__.
.. _e01ae-py2-py-references:
**References**
Huddleston, R E, 1974, `CDC 6600 routines for the interpolation of data and of data with derivatives`, SLL-74-0214, Sandia Laboratories (Reprint)
Krogh, F T, 1970, `Efficient algorithms for polynomial interpolation and numerical differentiation`, Math. Comput. (24), 185--190
"""
raise NotImplementedError
[docs]def dim1_spline(x, y):
r"""
``dim1_spline`` determines a cubic spline interpolant to a given set of data.
.. _e01ba-py2-py-doc:
For full information please refer to the NAG Library document for e01ba
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01baf.html
.. _e01ba-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{x}[\textit{i}-1]` must be set to :math:`x_{\textit{i}}`, the :math:`\textit{i}`\ th data value of the independent variable :math:`x`, for :math:`\textit{i} = 1,2,\ldots,m`.
**y** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{y}[\textit{i}-1]` must be set to :math:`y_{\textit{i}}`, the :math:`\textit{i}`\ th data value of the dependent variable :math:`y`, for :math:`\textit{i} = 1,2,\ldots,m`.
**Returns**
**lamda** : float, ndarray, shape :math:`\left(m+4\right)`
The value of :math:`\lambda_{\textit{i}}`, the :math:`\textit{i}`\ th knot, for :math:`\textit{i} = 1,2,\ldots,m+4`.
**c** : float, ndarray, shape :math:`\left(m\right)`
The coefficient :math:`c_{\textit{i}}` of the B-spline :math:`N_{\textit{i}}\left(x\right)`, for :math:`\textit{i} = 1,2,\ldots,m`. The remaining elements of the array are not used.
.. _e01ba-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{lck} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lck}\geq m+4`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 4`.
(`errno` :math:`2`)
On entry, :math:`\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{x}[\textit{I}-2] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{x}[\textit{I}-1] > \mathrm{x}[\textit{I}-2]`.
.. _e01ba-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_spline`` determines a cubic spline :math:`s\left(x\right)`, defined in the range :math:`x_1\leq x\leq x_m`, which interpolates (passes exactly through) the set of data points :math:`\left(x_{\textit{i}}, y_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,m`, where :math:`m\geq 4` and :math:`x_1 < x_2 < \cdots < x_m`.
Unlike some other spline interpolation algorithms, derivative end conditions are not imposed.
The spline interpolant chosen has :math:`m-4` interior knots :math:`\lambda_5,\lambda_6,\ldots,\lambda_m`, which are set to the values of :math:`x_3,x_4,\ldots,x_{{m-2}}` respectively.
This spline is represented in its B-spline form (see Cox (1975)):
.. math::
s\left(x\right) = \sum_{{i = 1}}^mc_iN_i\left(x\right)\text{,}
where :math:`N_i\left(x\right)` denotes the normalized B-spline of degree :math:`3`, defined upon the knots :math:`\lambda_i,\lambda_{{i+1}},\ldots,\lambda_{{i+4}}`, and :math:`c_i` denotes its coefficient, whose value is to be determined by the function.
The use of B-splines requires eight additional knots :math:`\lambda_1`, :math:`\lambda_2`, :math:`\lambda_3`, :math:`\lambda_4`, :math:`\lambda_{{m+1}}`, :math:`\lambda_{{m+2}}`, :math:`\lambda_{{m+3}}` and :math:`\lambda_{{m+4}}` to be specified; ``dim1_spline`` sets the first four of these to :math:`x_1` and the last four to :math:`x_m`.
The algorithm for determining the coefficients is as described in Cox (1975) except that :math:`QR` factorization is used instead of :math:`LU` decomposition.
The implementation of the algorithm involves setting up appropriate information for the related function :meth:`fit.dim1_spline_knots <naginterfaces.library.fit.dim1_spline_knots>` followed by a call of that function. (See :meth:`fit.dim1_spline_knots <naginterfaces.library.fit.dim1_spline_knots>` for further details.)
Values of the spline interpolant, or of its derivatives or definite integral, can subsequently be computed as detailed in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01baf.html#fcomments>`__.
.. _e01ba-py2-py-references:
**References**
Cox, M G, 1975, `An algorithm for spline interpolation`, J. Inst. Math. Appl. (15), 95--108
Cox, M G, 1977, `A survey of numerical methods for data and function approximation`, The State of the Art in Numerical Analysis, (ed D A H Jacobs), 627--668, Academic Press
"""
raise NotImplementedError
[docs]def dim1_monotonic(x, f):
r"""
``dim1_monotonic`` computes a monotonicity-preserving piecewise cubic Hermite interpolant to a set of data points.
.. _e01be-py2-py-doc:
For full information please refer to the NAG Library document for e01be
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01bef.html
.. _e01be-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{x}[\textit{r}-1]` must be set to :math:`x_{\textit{r}}`, the :math:`\textit{r}`\ th value of the independent variable (abscissa), for :math:`\textit{r} = 1,2,\ldots,n`.
**f** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{f}[\textit{r}-1]` must be set to :math:`f_{\textit{r}}`, the :math:`\textit{r}`\ th value of the dependent variable (ordinate), for :math:`\textit{r} = 1,2,\ldots,n`.
**Returns**
**d** : float, ndarray, shape :math:`\left(n\right)`
Estimates of derivatives at the data points. :math:`\mathrm{d}[r-1]` contains the derivative at :math:`\mathrm{x}[r-1]`.
.. _e01be-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 2`.
(`errno` :math:`2`)
On entry, :math:`r = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[r-2] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{x}[r-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{x}[r-2] < \mathrm{x}[r-1]` for all :math:`r`.
.. _e01be-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_monotonic`` estimates first derivatives at the set of data points :math:`\left(x_{\textit{r}}, f_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,n`, which determine a piecewise cubic Hermite interpolant to the data, that preserves monotonicity over ranges where the data points are monotonic.
If the data points are only piecewise monotonic, the interpolant will have an extremum at each point where monotonicity switches direction.
The estimates of the derivatives are computed by a formula due to Brodlie, which is described in Fritsch and Butland (1984), with suitable changes at the boundary points.
The function is derived from function PCHIM in Fritsch (1982).
Values of the computed interpolant, and of its first derivative and definite integral, can subsequently be computed by calling :meth:`dim1_monotonic_eval`, :meth:`dim1_monotonic_deriv` and :meth:`dim1_monotonic_intg`, as described in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01bef.html#fcomments>`__.
.. _e01be-py2-py-references:
**References**
Fritsch, F N, 1982, `PCHIP final specifications`, Report UCID-30194, Lawrence Livermore National Laboratory
Fritsch, F N and Butland, J, 1984, `A method for constructing local monotone piecewise cubic interpolants`, SIAM J. Sci. Statist. Comput. (5), 300--304
"""
raise NotImplementedError
[docs]def dim1_monotonic_eval(x, f, d, px):
r"""
``dim1_monotonic_eval`` evaluates a piecewise cubic Hermite interpolant at a set of points.
.. _e01bf-py2-py-doc:
For full information please refer to the NAG Library document for e01bf
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01bff.html
.. _e01bf-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`\textit{n}`, :math:`\mathrm{x}`, :math:`\mathrm{f}` and :math:`\mathrm{d}` must be unchanged from the previous call of :meth:`dim1_monotonic`.
**f** : float, array-like, shape :math:`\left(n\right)`
:math:`\textit{n}`, :math:`\mathrm{x}`, :math:`\mathrm{f}` and :math:`\mathrm{d}` must be unchanged from the previous call of :meth:`dim1_monotonic`.
**d** : float, array-like, shape :math:`\left(n\right)`
:math:`\textit{n}`, :math:`\mathrm{x}`, :math:`\mathrm{f}` and :math:`\mathrm{d}` must be unchanged from the previous call of :meth:`dim1_monotonic`.
**px** : float, array-like, shape :math:`\left(m\right)`
The :math:`m` values of :math:`x` at which the interpolant is to be evaluated.
**Returns**
**pf** : float, ndarray, shape :math:`\left(m\right)`
:math:`\mathrm{pf}[\textit{i}-1]` contains the value of the interpolant evaluated at the point :math:`\mathrm{px}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,m`.
.. _e01bf-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 2`.
(`errno` :math:`2`)
On entry, :math:`r = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[r-2] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{x}[r-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{x}[r-2] < \mathrm{x}[r-1]` for all :math:`r`.
(`errno` :math:`3`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`4`)
Warning -- some points in array :math:`\mathrm{px}` lie outside the range :math:`\mathrm{x}[0] \cdots \mathrm{x}[n-1]`. Values at these points are unreliable because computed by extrapolation.
.. _e01bf-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_monotonic_eval`` evaluates a piecewise cubic Hermite interpolant, as computed by :meth:`dim1_monotonic`, at the points :math:`\mathrm{px}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,m`.
If any point lies outside the interval from :math:`\mathrm{x}[0]` to :math:`\mathrm{x}[n-1]`, a value is extrapolated from the nearest extreme cubic, and a warning is returned.
The function is derived from function PCHFE in Fritsch (1982).
.. _e01bf-py2-py-references:
**References**
Fritsch, F N, 1982, `PCHIP final specifications`, Report UCID-30194, Lawrence Livermore National Laboratory
"""
raise NotImplementedError
[docs]def dim1_monotonic_deriv(x, f, d, px):
r"""
``dim1_monotonic_deriv`` evaluates a piecewise cubic Hermite interpolant and its first derivative at a set of points.
.. _e01bg-py2-py-doc:
For full information please refer to the NAG Library document for e01bg
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01bgf.html
.. _e01bg-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`\textit{n}`, :math:`\mathrm{x}`, :math:`\mathrm{f}` and :math:`\mathrm{d}` must be unchanged from the previous call of :meth:`dim1_monotonic`.
**f** : float, array-like, shape :math:`\left(n\right)`
:math:`\textit{n}`, :math:`\mathrm{x}`, :math:`\mathrm{f}` and :math:`\mathrm{d}` must be unchanged from the previous call of :meth:`dim1_monotonic`.
**d** : float, array-like, shape :math:`\left(n\right)`
:math:`\textit{n}`, :math:`\mathrm{x}`, :math:`\mathrm{f}` and :math:`\mathrm{d}` must be unchanged from the previous call of :meth:`dim1_monotonic`.
**px** : float, array-like, shape :math:`\left(m\right)`
The :math:`m` values of :math:`x` at which the interpolant is to be evaluated.
**Returns**
**pf** : float, ndarray, shape :math:`\left(m\right)`
:math:`\mathrm{pf}[\textit{i}-1]` contains the value of the interpolant evaluated at the point :math:`\mathrm{px}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,m`.
**pd** : float, ndarray, shape :math:`\left(m\right)`
:math:`\mathrm{pd}[\textit{i}-1]` contains the first derivative of the interpolant evaluated at the point :math:`\mathrm{px}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,m`.
.. _e01bg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 2`.
(`errno` :math:`2`)
On entry, :math:`r = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[r-2] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{x}[r-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{x}[r-2] < \mathrm{x}[r-1]` for all :math:`r`.
(`errno` :math:`3`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`4`)
Warning -- some points in array :math:`\mathrm{px}` lie outside the range :math:`\mathrm{x}[0] \cdots \mathrm{x}[n-1]`. Values at these points are unreliable because computed by extrapolation.
.. _e01bg-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_monotonic_deriv`` evaluates a piecewise cubic Hermite interpolant, as computed by :meth:`dim1_monotonic`, at the points :math:`\mathrm{px}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,m`.
The first derivatives at the points are also computed.
If any point lies outside the interval from :math:`\mathrm{x}[0]` to :math:`\mathrm{x}[n-1]`, values of the interpolant and its derivative are extrapolated from the nearest extreme cubic, and a warning is returned.
If values of the interpolant only, and not of its derivative, are required, :meth:`dim1_monotonic_eval` should be used.
The function is derived from function PCHFD in Fritsch (1982).
.. _e01bg-py2-py-references:
**References**
Fritsch, F N, 1982, `PCHIP final specifications`, Report UCID-30194, Lawrence Livermore National Laboratory
"""
raise NotImplementedError
[docs]def dim1_monotonic_intg(x, f, d, a, b):
r"""
``dim1_monotonic_intg`` evaluates the definite integral of a piecewise cubic Hermite interpolant over the interval :math:`\left[a, b\right]`.
.. _e01bh-py2-py-doc:
For full information please refer to the NAG Library document for e01bh
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01bhf.html
.. _e01bh-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`\textit{n}`, :math:`\mathrm{x}`, :math:`\mathrm{f}` and :math:`\mathrm{d}` must be unchanged from the previous call of :meth:`dim1_monotonic`.
**f** : float, array-like, shape :math:`\left(n\right)`
:math:`\textit{n}`, :math:`\mathrm{x}`, :math:`\mathrm{f}` and :math:`\mathrm{d}` must be unchanged from the previous call of :meth:`dim1_monotonic`.
**d** : float, array-like, shape :math:`\left(n\right)`
:math:`\textit{n}`, :math:`\mathrm{x}`, :math:`\mathrm{f}` and :math:`\mathrm{d}` must be unchanged from the previous call of :meth:`dim1_monotonic`.
**a** : float
The interval :math:`\left[a, b\right]` over which integration is to be performed.
**b** : float
The interval :math:`\left[a, b\right]` over which integration is to be performed.
**Returns**
**pint** : float
The value of the definite integral of the interpolant over the interval :math:`\left[a, b\right]`.
.. _e01bh-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 2`.
(`errno` :math:`2`)
On entry, :math:`r = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[r-2] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{x}[r-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{x}[r-2] < \mathrm{x}[r-1]` for all :math:`r`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
Warning -- either :math:`\mathrm{a}` or :math:`\mathrm{b}` is outside the range :math:`\mathrm{x}[0] \cdots \mathrm{x}[n-1]`. The result has been computed by extrapolation and is unreliable. :math:`\mathrm{a} = \langle\mathit{\boldsymbol{value}}\rangle` :math:`\mathrm{b} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _e01bh-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_monotonic_intg`` evaluates the definite integral of a piecewise cubic Hermite interpolant, as computed by :meth:`dim1_monotonic`, over the interval :math:`\left[a, b\right]`.
If either :math:`a` or :math:`b` lies outside the interval from :math:`\mathrm{x}[0]` to :math:`\mathrm{x}[n-1]` computation of the integral involves extrapolation and a warning is returned.
The function is derived from function PCHIA in Fritsch (1982).
.. _e01bh-py2-py-references:
**References**
Fritsch, F N, 1982, `PCHIP final specifications`, Report UCID-30194, Lawrence Livermore National Laboratory
"""
raise NotImplementedError
[docs]def dim1_monconv_disc(negfor, yfor, x, y, lam=0.2):
r"""
``dim1_monconv_disc`` computes, for a given set of data points, the forward values and other values required for monotone convex interpolation as defined in Hagan and West (2008).
This form of interpolation is particularly suited to the construction of yield curves in Financial Mathematics but can be applied to any data where it is desirable to preserve both monotonicity and convexity.
.. _e01ce-py2-py-doc:
For full information please refer to the NAG Library document for e01ce
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01cef.html
.. _e01ce-py2-py-parameters:
**Parameters**
**negfor** : bool
Determines whether or not to allow negative forward rates.
:math:`\mathrm{negfor} = \mathbf{True}`
Negative forward rates are permitted.
:math:`\mathrm{negfor} = \mathbf{False}`
Forward rates calculated must be non-negative.
**yfor** : bool
Determines whether the array :math:`\mathrm{y}` contains values, :math:`y`, or discrete forward rates :math:`f^d`.
:math:`\mathrm{yfor} = \mathbf{True}`
:math:`\mathrm{y}` contains the discrete forward rates :math:`f_i^d`, for :math:`\textit{i} = 1,2,\ldots,n`.
:math:`\mathrm{yfor} = \mathbf{False}`
:math:`\mathrm{y}` contains the values :math:`y_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`x`, the (possibly unordered) set of data points.
**y** : float, array-like, shape :math:`\left(n\right)`
If :math:`\mathrm{yfor} = \mathbf{True}`, the discrete forward rates :math:`f_i^d` corresponding to the data points :math:`x_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
If :math:`\mathrm{yfor} = \mathbf{False}`, the data values :math:`y_i` corresponding to the data points :math:`x_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
**lam** : float, optional
:math:`\lambda`, the amelioration (smoothing) parameter. Forward rates are first computed using `(2) <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01cef.html#eqn2>`__ and then, if :math:`\lambda > 0`, a limiting filter is applied which depends on neighbouring discrete forward values. This filter has a smoothing effect on the curve that increases with :math:`\lambda`.
**Returns**
**comm** : dict, communication object
Communication structure.
.. _e01ce-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 2`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{lam} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`0.0\leq \mathrm{lam}\leq 1.0`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{x}` contains duplicate data points.
.. _e01ce-py2-py-notes:
**Notes**
``dim1_monconv_disc`` computes, for a set of data points, :math:`\left(x_i, y_i\right)`, for :math:`\textit{i} = 1,2,\ldots,n`, the discrete forward rates, :math:`f_i^d`, and the instantaneous forward rates, :math:`f_i`, which are used in a monotone convex interpolation method that attempts to preserve both the monotonicity and the convexity of the original data.
The monotone convex interpolation method is due to Hagan and West and is described in Hagan and West (2006), Hagan and West (2008) and West (2011).
The discrete forward rates are defined simply, for ordered data, by
.. math::
\begin{array}{l} f_1^d = y_1\text{;} \\ f_i^d = \frac{{x_iy_i-x_{{i-1}}y_{{i-1}}}}{{x_i-x_{{i-1}}}} \text{, for } i = 2,3,\ldots,n\text{.}\end{array}
The discrete forward rates, if pre-computed, may be supplied instead of :math:`y`, in which case the original values :math:`y` are computed using the inverse of `(1) <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01cef.html#eqn1>`__.
The data points :math:`x_i` need not be ordered on input (though :math:`y_i` must correspond to :math:`x_i`); a set of ordered and scaled values :math:`\xi_i` are calculated from :math:`x_i` and stored.
In its simplest form, the instantaneous forward rates, :math:`f_i`, at the data points are computed as linear interpolations of the :math:`f_i^d`:
.. math::
\begin{array}{l} f_i = \frac{{x_i-x_{{i-1}}}}{{x_{{i+1}}-x_{{i-1}}}} f_{{i+1}}^d + \frac{{x_{{i+1}}-x_i}}{{x_{{i+1}}-x_{{i-1}}}} f_i^d \text{, for } i = 2,3,\ldots,{n-1} \\f_1 = f_2^d - \frac{1}{2} \left(f_2-f_2^d\right) \\ f_n = f_n^d - \frac{1}{2} \left(f_{{n-1}}-f_n^d\right)\text{.} \end{array}
If it is required, as a constraint, that these values should never be negative then a limiting filter is applied to :math:`f` as described in Section 3.6 of West (2011).
An ameliorated (smoothed) form of this linear interpolation for the forward rates is implemented using the amelioration (smoothing) parameter :math:`\lambda`.
For :math:`\lambda \equiv 0`, equation `(2) <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01cef.html#eqn2>`__ is used (with possible post-process filtering); for :math:`0 < \lambda \leq 1`, the ameliorated method described fully in West (2011) is used.
The values computed by ``dim1_monconv_disc`` are used by :meth:`dim1_monconv_eval` to compute, for a given value :math:`\hat{x}`, the monotone convex interpolated (or extrapolated) value :math:`\hat{y}\left(\hat{x}\right)` and the corresponding instantaneous forward rate :math:`f`; the curve gradient at :math:`\hat{x}` can be derived as :math:`y^{\prime } = \left(f-\hat{y}\right)/\hat{x}` for :math:`\hat{x}\neq 0`.
.. _e01ce-py2-py-references:
**References**
Hagan, P S and West, G, 2006, `Interpolation methods for curve construction`, Applied Mathematical Finance (13(2)), 89--129
Hagan, P S and West, G, 2008, `Methods for constructing a yield curve`, WILLMOTT Magazine (May), 70--81
West, G, 2011, `The monotone convex method of interpolation`, Financial Modelling Agency
"""
raise NotImplementedError
[docs]def dim1_monconv_eval(x, comm):
r"""
``dim1_monconv_eval`` evaluates a monotonic convex interpolant at a set of points.
.. _e01cf-py2-py-doc:
For full information please refer to the NAG Library document for e01cf
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01cff.html
.. _e01cf-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(m\right)`
:math:`x`, the points at which the interpolant is to be evaluated.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim1_monconv_disc`.
**Returns**
**val** : float, ndarray, shape :math:`\left(m\right)`
The values of the interpolant at :math:`x`.
**fwd** : float, ndarray, shape :math:`\left(m\right)`
The values of the forward rates at :math:`x`.
.. _e01cf-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Either :meth:`dim1_monconv_disc` was not called first or the communication array has become corrupted.
.. _e01cf-py2-py-notes:
**Notes**
``dim1_monconv_eval`` evaluates a monotonic convex interpolant, as setup by :meth:`dim1_monconv_disc`, at the points :math:`x`.
The function is derived from the work of Hagan and West and is described in Hagan and West (2006), Hagan and West (2008) and West (2011).
.. _e01cf-py2-py-references:
**References**
Hagan, P S and West, G, 2006, `Interpolation methods for curve construction`, Applied Mathematical Finance (13(2)), 89--129
Hagan, P S and West, G, 2008, `Methods for constructing a yield curve`, WILLMOTT Magazine (May), 70--81
West, G, 2011, `The monotone convex method of interpolation`, Financial Modelling Agency
"""
raise NotImplementedError
[docs]def dim2_spline_grid(x, y, f):
r"""
``dim2_spline_grid`` computes a bicubic spline interpolating surface through a set of data values, given on a rectangular grid in the :math:`x`-:math:`y` plane.
.. _e01da-py2-py-doc:
For full information please refer to the NAG Library document for e01da
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01daf.html
.. _e01da-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(\textit{mx}\right)`
:math:`\mathrm{x}[\textit{q}-1]` and :math:`\mathrm{y}[\textit{r}-1]` must contain :math:`x_{\textit{q}}`, for :math:`\textit{q} = 1,2,\ldots,m_x`, and :math:`y_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m_y`, respectively.
**y** : float, array-like, shape :math:`\left(\textit{my}\right)`
:math:`\mathrm{x}[\textit{q}-1]` and :math:`\mathrm{y}[\textit{r}-1]` must contain :math:`x_{\textit{q}}`, for :math:`\textit{q} = 1,2,\ldots,m_x`, and :math:`y_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m_y`, respectively.
**f** : float, array-like, shape :math:`\left(\textit{mx}\times \textit{my}\right)`
:math:`\mathrm{f}[m_y\times \left(\textit{q}-1\right)+\textit{r}-1]` must contain :math:`f_{{\textit{q},\textit{r}}}`, for :math:`\textit{r} = 1,2,\ldots,m_y`, for :math:`\textit{q} = 1,2,\ldots,m_x`.
**Returns**
**px** : int
:math:`\mathrm{px}` and :math:`\mathrm{py}` contain :math:`m_x+4` and :math:`m_y+4`, the total number of knots of the computed spline with respect to the :math:`x` and :math:`y` variables, respectively.
**py** : int
:math:`\mathrm{px}` and :math:`\mathrm{py}` contain :math:`m_x+4` and :math:`m_y+4`, the total number of knots of the computed spline with respect to the :math:`x` and :math:`y` variables, respectively.
**lamda** : float, ndarray, shape :math:`\left(\textit{mx}+4\right)`
:math:`\mathrm{lamda}` contains the complete set of knots :math:`\lambda_i` associated with the :math:`x` variable
**mu** : float, ndarray, shape :math:`\left(\textit{my}+4\right)`
:math:`\mathrm{mu}` contains the complete set of knots :math:`\mu_i` associated with the :math:`y` variable
**c** : float, ndarray, shape :math:`\left(\textit{mx}\times \textit{my}\right)`
The coefficients of the spline interpolant. :math:`\mathrm{c}[m_y\times \left(i-1\right)+j-1]` contains the coefficient :math:`c_{{ij}}` described in :ref:`Notes <e01da-py2-py-notes>`.
.. _e01da-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{my} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{my}\geq 4`.
(`errno` :math:`1`)
On entry, :math:`\textit{mx} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{mx}\geq 4`.
(`errno` :math:`2`)
On entry, the :math:`\mathrm{x}` or the :math:`\mathrm{y}` mesh points are not in strictly ascending order.
(`errno` :math:`3`)
An intermediate set of linear equations is singular -- the data is too ill-conditioned to compute :math:`B`-spline coefficients.
.. _e01da-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.`
``dim2_spline_grid`` determines a bicubic spline interpolant to the set of data points :math:`\left(x_{\textit{q}}, y_{\textit{r}}, f_{{\textit{q},\textit{r}}}\right)`, for :math:`\textit{r} = 1,2,\ldots,m_y`, for :math:`\textit{q} = 1,2,\ldots,m_x`.
The spline is given in the B-spline representation
.. math::
s\left(x, y\right) = \sum_{{i = 1}}^{m_x}\sum_{{j = 1}}^{m_y}c_{{ij}}M_i\left(x\right)N_j\left(y\right)\text{,}
such that
.. math::
s\left(x_q, y_r\right) = f_{{q,r}}\text{,}
where :math:`M_i\left(x\right)` and :math:`N_j\left(y\right)` denote normalized cubic B-splines, the former defined on the knots :math:`\lambda_i` to :math:`\lambda_{{i+4}}` and the latter on the knots :math:`\mu_j` to :math:`\mu_{{j+4}}`, and the :math:`c_{{ij}}` are the spline coefficients.
These knots, as well as the coefficients, are determined by the function, which is derived from the function B2IRE in Anthony `et al.` (1982).
The method used is described in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01daf.html#fcomments2>`__.
For further information on splines, see Hayes and Halliday (1974) for bicubic splines and de Boor (1972) for normalized B-splines.
Values and derivatives of the computed spline can subsequently be computed by calling :meth:`fit.dim2_spline_evalv <naginterfaces.library.fit.dim2_spline_evalv>`, :meth:`fit.dim2_spline_evalm <naginterfaces.library.fit.dim2_spline_evalm>` or :meth:`fit.dim2_spline_derivm <naginterfaces.library.fit.dim2_spline_derivm>` as described in `Evaluation of Computed Spline <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01daf.html#fcomments3>`__.
.. _e01da-py2-py-references:
**References**
Anthony, G T, Cox, M G and Hayes, J G, 1982, `DASL -- Data Approximation Subroutine Library`, National Physical Laboratory
Cox, M G, 1975, `An algorithm for spline interpolation`, J. Inst. Math. Appl. (15), 95--108
de Boor, C, 1972, `On calculating with B-splines`, J. Approx. Theory (6), 50--62
Hayes, J G and Halliday, J, 1974, `The least squares fitting of cubic spline surfaces to general data sets`, J. Inst. Math. Appl. (14), 89--103
"""
raise NotImplementedError
[docs]def dim2_triangulate(x, y):
r"""
``dim2_triangulate`` generates a triangulation for a given set of two-dimensional points using the method of Renka and Cline.
.. _e01ea-py2-py-doc:
For full information please refer to the NAG Library document for e01ea
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01eaf.html
.. _e01ea-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
The :math:`x` coordinates of the :math:`n` data points.
**y** : float, array-like, shape :math:`\left(n\right)`
The :math:`y` coordinates of the :math:`n` data points.
**Returns**
**triang** : int, ndarray, shape :math:`\left(7\times n\right)`
A data structure defining the computed triangulation, in a form suitable for passing to :meth:`dim2_triang_bary_eval`. Details of how the triangulation is encoded in :math:`\mathrm{triang}` are given in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01eaf.html#fcomments>`__. These details are most likely to be of use when plotting the computed triangulation.
.. _e01ea-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 3`.
(`errno` :math:`2`)
On entry, all the :math:`\left(x, y\right)` pairs are collinear.
.. _e01ea-py2-py-notes:
**Notes**
``dim2_triangulate`` creates a Thiessen triangulation with a given set of two-dimensional data points as nodes.
This triangulation will be as equiangular as possible (Cline and Renka (1984)).
See Renka and Cline (1984) for more detailed information on the algorithm, a development of that by Lawson (1977).
The code is derived from Renka (1984).
The computed triangulation is returned in a form suitable for passing to :meth:`dim2_triang_bary_eval` which, for a set of nodal function values, computes interpolated values at a set of points.
.. _e01ea-py2-py-references:
**References**
Cline, A K and Renka, R L, 1984, `A storage-efficient method for construction of a Thiessen triangulation`, Rocky Mountain J. Math. (14), 119--139
Lawson, C L, 1977, `Software for` :math:`C^1` `surface interpolation`, Mathematical Software III, (ed J R Rice), 161--194, Academic Press
Renka, R L, 1984, `Algorithm 624: triangulation and interpolation of arbitrarily distributed points in the plane`, ACM Trans. Math. Software (10), 440--442
Renka, R L and Cline, A K, 1984, `A triangle-based` :math:`C^1` `interpolation method`, Rocky Mountain J. Math. (14), 223--237
"""
raise NotImplementedError
[docs]def dim2_triang_bary_eval(x, y, f, triang, px, py):
r"""
``dim2_triang_bary_eval`` performs barycentric interpolation, at a given set of points, using a set of function values on a scattered grid and a triangulation of that grid computed by :meth:`dim2_triangulate`.
.. _e01eb-py2-py-doc:
For full information please refer to the NAG Library document for e01eb
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01ebf.html
.. _e01eb-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
The coordinates of the :math:`\textit{r}`\ th data point, :math:`\left(x_r, y_r\right)`, for :math:`\textit{r} = 1,2,\ldots,n`. :math:`\mathrm{x}` and :math:`\mathrm{y}` must be unchanged from the previous call of :meth:`dim2_triangulate`.
**y** : float, array-like, shape :math:`\left(n\right)`
The coordinates of the :math:`\textit{r}`\ th data point, :math:`\left(x_r, y_r\right)`, for :math:`\textit{r} = 1,2,\ldots,n`. :math:`\mathrm{y}` and :math:`\mathrm{y}` must be unchanged from the previous call of :meth:`dim2_triangulate`.
**f** : float, array-like, shape :math:`\left(n\right)`
The function values :math:`f_{\textit{r}}` at :math:`\left(x_{\textit{r}}, y_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,n`.
**triang** : int, array-like, shape :math:`\left(7\times n\right)`
The triangulation computed by the previous call of :meth:`dim2_triangulate`. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01eaf.html#fcomments>`__ for details of how the triangulation used is encoded in :math:`\mathrm{triang}`.
**px** : float, array-like, shape :math:`\left(m\right)`
The coordinates :math:`\left(\textit{px}_{\textit{i}}, \textit{py}_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,m`, at which interpolated function values are sought.
**py** : float, array-like, shape :math:`\left(m\right)`
The coordinates :math:`\left(\textit{px}_{\textit{i}}, \textit{py}_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,m`, at which interpolated function values are sought.
**Returns**
**pf** : float, ndarray, shape :math:`\left(m\right)`
The interpolated values :math:`F\left(\textit{px}_{\textit{i}}, \textit{py}_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,m`.
.. _e01eb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 3`.
(`errno` :math:`2`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 1`.
(`errno` :math:`3`)
On entry, the triangulation information held in the array :math:`\mathrm{triang}` does not specify a valid triangulation of the data points. :math:`\mathrm{triang}` has been corrupted since the call to :meth:`dim2_triangulate`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`4`)
At least one evaluation point lies outside the nodal triangulation. For each such point the value returned in :math:`\mathrm{pf}` is that corresponding to a node on the closest boundary line segment.
.. _e01eb-py2-py-notes:
**Notes**
``dim2_triang_bary_eval`` takes as input a set of scattered data points :math:`\left(x_{\textit{r}}, y_{\textit{r}}, f_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,n`, and a Thiessen triangulation of the :math:`\left(x_r, y_r\right)` computed by :meth:`dim2_triangulate`, and interpolates at a set of points :math:`\left(\textit{px}_i, \textit{py}_i\right)`, for :math:`\textit{i} = 1,2,\ldots,m`.
If the :math:`i`\ th interpolation point :math:`\left(\textit{px}_i, \textit{py}_i\right)` is equal to :math:`\left(x_r, y_r\right)` for some value of :math:`r`, the returned value will be equal to :math:`f_r`; otherwise a barycentric transformation will be used to calculate the interpolant.
For each point :math:`\left(\textit{px}_i, \textit{py}_i\right)`, a triangle is sought which contains the point; the vertices of the triangle and :math:`f_r` values at the vertices are then used to compute the value :math:`F\left(\textit{px}_i, \textit{py}_i\right)`.
If any interpolation point lies outside the triangulation defined by the input arguments, the returned value is the value provided, :math:`f_s`, at the closest node :math:`\left(x_s, y_s\right)`.
``dim2_triang_bary_eval`` must only be called after a call to :meth:`dim2_triangulate`.
.. _e01eb-py2-py-references:
**References**
Cline, A K and Renka, R L, 1984, `A storage-efficient method for construction of a Thiessen triangulation`, Rocky Mountain J. Math. (14), 119--139
Lawson, C L, 1977, `Software for` :math:`C^1` `surface interpolation`, Mathematical Software III, (ed J R Rice), 161--194, Academic Press
Renka, R L, 1984, `Algorithm 624: triangulation and interpolation of arbitrarily distributed points in the plane`, ACM Trans. Math. Software (10), 440--442
Renka, R L and Cline, A K, 1984, `A triangle-based` :math:`C^1` `interpolation method`, Rocky Mountain J. Math. (14), 223--237
"""
raise NotImplementedError
[docs]def dim1_ratnl(x, f):
r"""
``dim1_ratnl`` produces, from a set of function values and corresponding abscissae, the coefficients of an interpolating rational function expressed in continued fraction form.
.. _e01ra-py2-py-doc:
For full information please refer to the NAG Library document for e01ra
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01raf.html
.. _e01ra-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{x}[\textit{i}-1]` must be set to the value of the :math:`\textit{i}`\ th data abscissa, :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
**f** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{f}[\textit{i}-1]` must be set to the value of the data ordinate, :math:`f_{\textit{i}}`, corresponding to :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
**Returns**
**m** : int
:math:`m`, the number of terms in the continued fraction representation of :math:`R\left(x\right)`.
**a** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{a}[\textit{j}-1]` contains the value of the parameter :math:`a_{\textit{j}}` in :math:`R\left(x\right)`, for :math:`\textit{j} = 1,2,\ldots,m`. The remaining elements of :math:`\mathrm{a}`, if any, are set to zero.
**u** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{u}[\textit{j}-1]` contains the value of the parameter :math:`u_{\textit{j}}` in :math:`R\left(x\right)`, for :math:`\textit{j} = 1,2,\ldots,m-1`. The :math:`u_j` are a permuted subset of the elements of :math:`\mathrm{x}`. The remaining :math:`n-m+1` locations contain a permutation of the remaining :math:`x_i`, which can be ignored.
.. _e01ra-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{x}[\textit{I}-1]` is very close to :math:`\mathrm{x}[\textit{J}-1]`: :math:`\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{x}[\textit{J}-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
A continued fraction of the required form does not exist.
.. _e01ra-py2-py-notes:
**Notes**
``dim1_ratnl`` produces the parameters of a rational function :math:`R\left(x\right)` which assumes prescribed values :math:`f_i` at prescribed values :math:`x_i` of the independent variable :math:`x`, for :math:`\textit{i} = 1,2,\ldots,n`.
More specifically, ``dim1_ratnl`` determines the parameters :math:`a_j`, for :math:`\textit{j} = 1,2,\ldots,m` and :math:`u_j`, for :math:`\textit{j} = 1,2,\ldots,m-1`, in the continued fraction
.. math::
R\left(x\right) = a_1+R_m\left(x\right)
where
.. math::
R_i\left(x\right) = \frac{{a_{{m-i+2}}\left(x-u_{{m-i+1}}\right)}}{{1+R_{{i-1}}\left(x\right)}}\text{, for }i = m,m-1,\ldots,2\text{,}
and
.. math::
R_1\left(x\right) = 0\text{,}
such that :math:`R\left(x_i\right) = f_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
The value of :math:`m` in `(1) <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01raf.html#eqn1>`__ is determined by the function; normally :math:`m = n`.
The values of :math:`u_j` form a reordered subset of the values of :math:`x_i` and their ordering is designed to ensure that a representation of the form `(1) <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01raf.html#eqn1>`__ is determined whenever one exists.
The subsequent evaluation of `(1) <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01raf.html#eqn1>`__ for given values of :math:`x` can be carried out using :meth:`dim1_ratnl_eval`.
The computational method employed in ``dim1_ratnl`` is the modification of the Thacher--Tukey algorithm described in Graves--Morris and Hopkins (1981).
.. _e01ra-py2-py-references:
**References**
Graves--Morris, P R and Hopkins, T R, 1981, `Reliable rational interpolation`, Numer. Math. (36), 111--128
"""
raise NotImplementedError
[docs]def dim1_ratnl_eval(a, u, x):
r"""
``dim1_ratnl_eval`` evaluates continued fractions of the form produced by :meth:`dim1_ratnl`.
.. _e01rb-py2-py-doc:
For full information please refer to the NAG Library document for e01rb
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01rbf.html
.. _e01rb-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{a}[\textit{j}-1]` must be set to the value of the parameter :math:`a_{\textit{j}}` in the continued fraction, for :math:`\textit{j} = 1,2,\ldots,m`.
**u** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{u}[\textit{j}-1]` must be set to the value of the parameter :math:`u_{\textit{j}}` in the continued fraction, for :math:`\textit{j} = 1,2,\ldots,m-1`. (The element :math:`\mathrm{u}[m-1]` is not used).
**x** : float
The value of :math:`x` at which the continued fraction is to be evaluated.
**Returns**
**f** : float
The value of the continued fraction corresponding to the value of :math:`x`.
.. _e01rb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
:math:`\mathrm{x}` corresponds to a pole of :math:`R\left(x\right)`, or is very close. :math:`\mathrm{x} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _e01rb-py2-py-notes:
**Notes**
``dim1_ratnl_eval`` evaluates the continued fraction
.. math::
R\left(x\right) = a_1+R_m\left(x\right)
where
.. math::
R_i\left(x\right) = \frac{{a_{{m-i+2}}\left(x-u_{{m-i+1}}\right)}}{{1+R_{{i-1}}\left(x\right)}}\text{, for }i = m,m-1,\ldots,2\text{.}
and
.. math::
R_1\left(x\right) = 0
for a prescribed value of :math:`x`. ``dim1_ratnl_eval`` is intended to be used to evaluate the continued fraction representation (of an interpolatory rational function) produced by :meth:`dim1_ratnl`.
.. _e01rb-py2-py-references:
**References**
Graves--Morris, P R and Hopkins, T R, 1981, `Reliable rational interpolation`, Numer. Math. (36), 111--128
"""
raise NotImplementedError
[docs]def dim2_scat(x, y, f):
r"""
``dim2_scat`` generates a two-dimensional surface interpolating a set of scattered data points, using the method of Renka and Cline.
.. _e01sa-py2-py-doc:
For full information please refer to the NAG Library document for e01sa
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01saf.html
.. _e01sa-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(m\right)`
The coordinates of the :math:`\textit{r}`\ th data point, for :math:`\textit{r} = 1,2,\ldots,m`. The data points are accepted in any order, but see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01saf.html#fcomments>`__.
**y** : float, array-like, shape :math:`\left(m\right)`
The coordinates of the :math:`\textit{r}`\ th data point, for :math:`\textit{r} = 1,2,\ldots,m`. The data points are accepted in any order, but see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01saf.html#fcomments>`__.
**f** : float, array-like, shape :math:`\left(m\right)`
The coordinates of the :math:`\textit{r}`\ th data point, for :math:`\textit{r} = 1,2,\ldots,m`. The data points are accepted in any order, but see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01saf.html#fcomments>`__.
**Returns**
**triang** : int, ndarray, shape :math:`\left(7\times m\right)`
A data structure defining the computed triangulation, in a form suitable for passing to :meth:`dim2_scat_eval`.
**grads** : float, ndarray, shape :math:`\left(2, m\right)`
The estimated partial derivatives at the nodes, in a form suitable for passing to :meth:`dim2_scat_eval`. The derivatives at node :math:`\textit{r}` with respect to :math:`x` and :math:`y` are contained in :math:`\mathrm{grads}[0,\textit{r}-1]` and :math:`\mathrm{grads}[1,\textit{r}-1]` respectively, for :math:`\textit{r} = 1,2,\ldots,m`.
.. _e01sa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 3`.
(`errno` :math:`2`)
All nodes are collinear. There is no unique solution.
(`errno` :math:`3`)
On entry, :math:`\left({\mathrm{x}[\textit{I}-1]}, {\mathrm{y}[\textit{I}-1]}\right) = \left({\mathrm{x}[\textit{J}-1]}, {\mathrm{y}[\textit{J}-1]}\right)`, for :math:`\textit{I},\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle\langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{x}[\textit{I}-1]`, :math:`\mathrm{y}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle\langle\mathit{\boldsymbol{value}}\rangle`.
.. _e01sa-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.`
``dim2_scat`` constructs an interpolating surface :math:`F\left(x, y\right)` through a set of :math:`m` scattered data points :math:`\left(x_{\textit{r}}, y_{\textit{r}}, f_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,m`, using a method due to Renka and Cline.
In the :math:`\left(x, y\right)` plane, the data points must be distinct.
The constructed surface is continuous and has continuous first derivatives.
The method involves firstly creating a triangulation with all the :math:`\left(x, y\right)` data points as nodes, the triangulation being as nearly equiangular as possible (see Cline and Renka (1984)).
Then gradients in the :math:`x`- and :math:`y`-directions are estimated at node :math:`\textit{r}`, for :math:`\textit{r} = 1,2,\ldots,m`, as the partial derivatives of a quadratic function of :math:`x` and :math:`y` which interpolates the data value :math:`f_r`, and which fits the data values at nearby nodes (those within a certain distance chosen by the algorithm) in a weighted least squares sense.
The weights are chosen such that closer nodes have more influence than more distant nodes on derivative estimates at node :math:`r`.
The computed partial derivatives, with the :math:`f_r` values, at the three nodes of each triangle define a piecewise polynomial surface of a certain form which is the interpolant on that triangle.
See Renka and Cline (1984) for more detailed information on the algorithm, a development of that by Lawson (1977).
The code is derived from Renka (1984).
The interpolant :math:`F\left(x, y\right)` can subsequently be evaluated at any point :math:`\left(x, y\right)` inside or outside the domain of the data by a call to :meth:`dim2_scat_eval`. Points outside the domain are evaluated by extrapolation.
.. _e01sa-py2-py-references:
**References**
Cline, A K and Renka, R L, 1984, `A storage-efficient method for construction of a Thiessen triangulation`, Rocky Mountain J. Math. (14), 119--139
Lawson, C L, 1977, `Software for` :math:`C^1` `surface interpolation`, Mathematical Software III, (ed J R Rice), 161--194, Academic Press
Renka, R L, 1984, `Algorithm 624: triangulation and interpolation of arbitrarily distributed points in the plane`, ACM Trans. Math. Software (10), 440--442
Renka, R L and Cline, A K, 1984, `A triangle-based` :math:`C^1` `interpolation method`, Rocky Mountain J. Math. (14), 223--237
"""
raise NotImplementedError
[docs]def dim2_scat_eval(x, y, f, triang, grads, px, py, ist=1):
r"""
``dim2_scat_eval`` evaluates at a given point the two-dimensional interpolant function computed by :meth:`dim2_scat`.
.. _e01sb-py2-py-doc:
For full information please refer to the NAG Library document for e01sb
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01sbf.html
.. _e01sb-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{x}` must be unchanged from the previous call of :meth:`dim2_scat`
**y** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{y}` must be unchanged from the previous call of :meth:`dim2_scat`
**f** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{f}` must be unchanged from the previous call of :meth:`dim2_scat`
**triang** : int, array-like, shape :math:`\left(7\times m\right)`
:math:`\mathrm{triang}` must be unchanged from the previous call of :meth:`dim2_scat`
**grads** : float, array-like, shape :math:`\left(2, m\right)`
:math:`\mathrm{grads}` must be unchanged from the previous call of :meth:`dim2_scat`
**px** : float
The point :math:`\left({px}, {py}\right)` at which the interpolant is to be evaluated.
**py** : float
The point :math:`\left({px}, {py}\right)` at which the interpolant is to be evaluated.
**ist** : int, optional
The index of the starting node in the search for a triangle containing the point :math:`\left({px}, {py}\right)`. On the first call to ``dim2_scat_eval``, :math:`\mathrm{ist}` must be set to :math:`1`. For efficiency on subsequent calls to ``dim2_scat_eval`` an updated value of :math:`\mathrm{ist}` as returned by ``dim2_scat_eval`` may be supplied instead. An input value outside the range :math:`1\leq \mathrm{ist}\leq m` will be treated as :math:`1`.
**Returns**
**ist** : int
The index of one of the vertices of the triangle containing the point :math:`\left({px}, {py}\right)`.
**pf** : float
The value of the interpolant evaluated at the point :math:`\left({px}, {py}\right)`.
.. _e01sb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 3`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{triang}` does not contain a valid data point triangulation; :math:`\mathrm{triang}` may have been corrupted since the call to :meth:`dim2_scat`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
Warning -- the evaluation point :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)` lies outside the triangulation boundary. The returned value was computed by extrapolation.
.. _e01sb-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.`
``dim2_scat_eval`` takes as input the arguments defining the interpolant :math:`F\left(x, y\right)` of a set of scattered data points :math:`\left(x_r, y_r, f_r\right)`, for :math:`\textit{r} = 1,2,\ldots,m`, as computed by :meth:`dim2_scat`, and evaluates the interpolant at the point :math:`\left({px}, {py}\right)`.
If :math:`\left({px}, {py}\right)` is equal to :math:`\left(x_r, y_r\right)` for some value of :math:`r`, the returned value will be equal to :math:`f_r`.
If :math:`\left({px}, {py}\right)` is not equal to :math:`\left(x_r, y_r\right)` for any :math:`r`, the derivatives in :math:`\mathrm{grads}` will be used to compute the interpolant.
A triangle is sought which contains the point :math:`\left({px}, {py}\right)`, and the vertices of the triangle along with the partial derivatives and :math:`f_r` values at the vertices are used to compute the value :math:`F\left({px}, {py}\right)`.
If the point :math:`\left({px}, {py}\right)` lies outside the triangulation defined by the input arguments, the returned value is obtained by extrapolation.
In this case, the interpolating function :math:`\mathrm{f}` is extended linearly beyond the triangulation boundary.
The method is described in more detail in Renka and Cline (1984) and the code is derived from Renka (1984).
``dim2_scat_eval`` must only be called after a call to :meth:`dim2_scat`.
.. _e01sb-py2-py-references:
**References**
Renka, R L, 1984, `Algorithm 624: triangulation and interpolation of arbitrarily distributed points in the plane`, ACM Trans. Math. Software (10), 440--442
Renka, R L and Cline, A K, 1984, `A triangle-based` :math:`C^1` `interpolation method`, Rocky Mountain J. Math. (14), 223--237
"""
raise NotImplementedError
[docs]def dim2_scat_shep(x, y, f, nw, nq):
r"""
``dim2_scat_shep`` generates a two-dimensional interpolant to a set of scattered data points, using a modified Shepard method.
.. _e01sg-py2-py-doc:
For full information please refer to the NAG Library document for e01sg
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01sgf.html
.. _e01sg-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(m\right)`
The Cartesian coordinates of the data points :math:`\left(x_{\textit{r}}, y_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,m`.
**y** : float, array-like, shape :math:`\left(m\right)`
The Cartesian coordinates of the data points :math:`\left(x_{\textit{r}}, y_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,m`.
**f** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{f}[\textit{r}-1]` must be set to the data value :math:`f_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m`.
**nw** : int
The number :math:`N_w` of data points that determines each radius of influence :math:`R_w`, appearing in the definition of each of the weights :math:`w_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m` (see :ref:`Notes <e01sg-py2-py-notes>`). Note that :math:`R_w` is different for each weight. If :math:`\mathrm{nw}\leq 0` the default value :math:`\mathrm{nw} = \mathrm{min}\left(19, {m-1}\right)` is used instead.
**nq** : int
The number :math:`N_q` of data points to be used in the least squares fit for coefficients defining the nodal functions :math:`q_r\left(x, y\right)` (see :ref:`Notes <e01sg-py2-py-notes>`). If :math:`\mathrm{nq}\leq 0` the default value :math:`\mathrm{nq} = \mathrm{min}\left(13, {m-1}\right)` is used instead.
**Returns**
**iq** : int, ndarray, shape :math:`\left(2\times m+1\right)`
Integer data defining the interpolant :math:`Q\left(x, y\right)`.
**rq** : float, ndarray, shape :math:`\left(6\times m+5\right)`
Real data defining the interpolant :math:`Q\left(x, y\right)`.
.. _e01sg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{lrq}` is too small: :math:`\textit{lrq} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\textit{liq}` is too small: :math:`\textit{liq} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nw}\leq \mathrm{min}\left(40, {m-1}\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nq} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nq}\leq \mathrm{min}\left(40, {m-1}\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nq} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nq} \leq 0` or :math:`\mathrm{nq}\geq 5`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 6`.
(`errno` :math:`2`)
There are duplicate nodes in the dataset. :math:`\left({\mathrm{x}[\textit{I}-1]}, {\mathrm{y}[\textit{I}-1]}\right) = \left({\mathrm{x}[\textit{J}-1]}, {\mathrm{y}[\textit{J}-1]}\right)`, for :math:`\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle`. The interpolant cannot be derived.
(`errno` :math:`3`)
All nodes are collinear. There is no unique solution.
.. _e01sg-py2-py-notes:
**Notes**
``dim2_scat_shep`` constructs a smooth function :math:`Q\left(x, y\right)` which interpolates a set of :math:`m` scattered data points :math:`\left(x_r, y_r, f_r\right)`, for :math:`r = 1,2,\ldots,m`, using a modification of Shepard's method.
The surface is continuous and has continuous first partial derivatives.
The basic Shepard (1968) method interpolates the input data with the weighted mean
.. math::
Q\left(x, y\right) = \frac{{\sum_{{r = 1}}^mw_r\left(x, y\right)q_r}}{{\sum_{{r = 1}}^mw_r\left(x, y\right)}}\text{,}
where :math:`q_r = f_r`, :math:`w_r\left(x, y\right) = \frac{1}{{d_r^2}}` and :math:`d_r^2 = \left(x-x_r\right)^2+\left(y-y_r\right)^2`.
The basic method is global in that the interpolated value at any point depends on all the data, but this function uses a modification (see Franke and Nielson (1980) and Renka (1988a)), whereby the method becomes local by adjusting each :math:`w_r\left(x, y\right)` to be zero outside a circle with centre :math:`\left(x_r, y_r\right)` and some radius :math:`R_w`.
Also, to improve the performance of the basic method, each :math:`q_r` above is replaced by a function :math:`q_r\left(x, y\right)`, which is a quadratic fitted by weighted least squares to data local to :math:`\left(x_r, y_r\right)` and forced to interpolate :math:`\left(x_r, y_r, f_r\right)`.
In this context, a point :math:`\left(x, y\right)` is defined to be local to another point if it lies within some distance :math:`R_q` of it.
Computation of these quadratics constitutes the main work done by this function.
The efficiency of the function is further enhanced by using a cell method for nearest neighbour searching due to Bentley and Friedman (1979).
The radii :math:`R_w` and :math:`R_q` are chosen to be just large enough to include :math:`N_w` and :math:`N_q` data points, respectively, for user-supplied constants :math:`N_w` and :math:`N_q`.
Default values of these arguments are provided by the function, and advice on alternatives is given in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01sgf.html#fcomments2>`__.
This function is derived from the function QSHEP2 described by Renka (1988b).
Values of the interpolant :math:`Q\left(x, y\right)` generated by this function, and its first partial derivatives, can subsequently be evaluated for points in the domain of the data by a call to :meth:`dim2_scat_shep_eval`.
.. _e01sg-py2-py-references:
**References**
Bentley, J L and Friedman, J H, 1979, `Data structures for range searching`, ACM Comput. Surv. (11), 397--409
Franke, R and Nielson, G, 1980, `Smooth interpolation of large sets of scattered data`, Internat. J. Num. Methods Engrg. (15), 1691--1704
Renka, R J, 1988, `Algorithm 660: QSHEP2D: Quadratic Shepard method for bivariate interpolation of scattered data`, ACM Trans. Math. Software (14), 149--150
Renka, R J, 1988, `Multivariate interpolation of large sets of scattered data`, ACM Trans. Math. Software (14), 139--148
Shepard, D, 1968, `A two-dimensional interpolation function for irregularly spaced data`, Proc. 23rd Nat. Conf. ACM, 517--523, Brandon/Systems Press Inc., Princeton
"""
raise NotImplementedError
[docs]def dim2_scat_shep_eval(x, y, f, iq, rq, u, v):
r"""
``dim2_scat_shep_eval`` evaluates the two-dimensional interpolating function generated by :meth:`dim2_scat_shep` and its first partial derivatives.
.. _e01sh-py2-py-doc:
For full information please refer to the NAG Library document for e01sh
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01shf.html
.. _e01sh-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(m\right)`
:math:`\textit{m}`, :math:`\mathrm{x}`, :math:`\mathrm{y}` and :math:`\mathrm{f}` must be the same values as were supplied in the preceding call to :meth:`dim2_scat_shep`.
**y** : float, array-like, shape :math:`\left(m\right)`
:math:`\textit{m}`, :math:`\mathrm{x}`, :math:`\mathrm{y}` and :math:`\mathrm{f}` must be the same values as were supplied in the preceding call to :meth:`dim2_scat_shep`.
**f** : float, array-like, shape :math:`\left(m\right)`
:math:`\textit{m}`, :math:`\mathrm{x}`, :math:`\mathrm{y}` and :math:`\mathrm{f}` must be the same values as were supplied in the preceding call to :meth:`dim2_scat_shep`.
**iq** : int, array-like, shape :math:`\left(2\times m+1\right)`
Must be unchanged from the value returned from a previous call to :meth:`dim2_scat_shep`.
**rq** : float, array-like, shape :math:`\left(6\times m+5\right)`
Must be unchanged from the value returned from a previous call to :meth:`dim2_scat_shep`.
**u** : float, array-like, shape :math:`\left(n\right)`
The evaluation points :math:`\left(u_{\textit{i}}, v_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`.
**v** : float, array-like, shape :math:`\left(n\right)`
The evaluation points :math:`\left(u_{\textit{i}}, v_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`.
**Returns**
**q** : float, ndarray, shape :math:`\left(n\right)`
The values of the interpolant at :math:`\left(u_{\textit{i}}, v_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`. If any of these evaluation points lie outside the region of definition of the interpolant the corresponding entries in :math:`\mathrm{q}` are set to an extrapolated approximation, and ``dim2_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
**qx** : float, ndarray, shape :math:`\left(n\right)`
The values of the partial derivatives of the interpolant :math:`Q\left(x, y\right)` at :math:`\left(u_{\textit{i}}, v_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`. If any of these evaluation points lie outside the region of definition of the interpolant, the corresponding entries in :math:`\mathrm{qx}` and :math:`\mathrm{qy}` are set to extrapolated approximations to the partial derivatives, and ``dim2_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
**qy** : float, ndarray, shape :math:`\left(n\right)`
The values of the partial derivatives of the interpolant :math:`Q\left(x, y\right)` at :math:`\left(u_{\textit{i}}, v_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`. If any of these evaluation points lie outside the region of definition of the interpolant, the corresponding entries in :math:`\mathrm{qx}` and :math:`\mathrm{qy}` are set to extrapolated approximations to the partial derivatives, and ``dim2_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
.. _e01sh-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{lrq}` is too small: :math:`\textit{lrq} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\textit{liq}` is too small: :math:`\textit{liq} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 6`.
(`errno` :math:`2`)
On entry, values in :math:`\mathrm{rq}` appear to be invalid. Check that :math:`\mathrm{rq}` has not been corrupted between calls to :meth:`dim2_scat_shep` and ``dim2_scat_shep_eval``.
(`errno` :math:`2`)
On entry, values in :math:`\mathrm{iq}` appear to be invalid. Check that :math:`\mathrm{iq}` has not been corrupted between calls to :meth:`dim2_scat_shep` and ``dim2_scat_shep_eval``.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
On entry, at least one evaluation point lies outside the region of definition of the interpolant. At such points the corresponding values in :math:`\mathrm{q}` and :math:`\mathrm{qx}` contain extrapolated approximations. Points should be evaluated one by one to identify extrapolated values.
.. _e01sh-py2-py-notes:
**Notes**
``dim2_scat_shep_eval`` takes as input the interpolant :math:`Q\left(x, y\right)` of a set of scattered data points :math:`\left(x_r, y_r, f_r\right)`, for :math:`\textit{r} = 1,2,\ldots,m`, as computed by :meth:`dim2_scat_shep`, and evaluates the interpolant and its first partial derivatives at the set of points :math:`\left(u_i, v_i\right)`, for :math:`\textit{i} = 1,2,\ldots,n`.
``dim2_scat_shep_eval`` must only be called after a call to :meth:`dim2_scat_shep`.
This function is derived from the function QS2GRD described by Renka (1988).
.. _e01sh-py2-py-references:
**References**
Renka, R J, 1988, `Algorithm 660: QSHEP2D: Quadratic Shepard method for bivariate interpolation of scattered data`, ACM Trans. Math. Software (14), 149--150
"""
raise NotImplementedError
[docs]def dim3_scat_shep(x, y, z, f, nw, nq):
r"""
``dim3_scat_shep`` generates a three-dimensional interpolant to a set of scattered data points, using a modified Shepard method.
.. _e01tg-py2-py-doc:
For full information please refer to the NAG Library document for e01tg
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01tgf.html
.. _e01tg-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{x}[\textit{r}-1]`, :math:`\mathrm{y}[\textit{r}-1]`, :math:`\mathrm{z}[\textit{r}-1]` must be set to the Cartesian coordinates of the data point :math:`\left(x_{\textit{r}}, y_{\textit{r}}, z_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,m`.
**y** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{x}[\textit{r}-1]`, :math:`\mathrm{y}[\textit{r}-1]`, :math:`\mathrm{z}[\textit{r}-1]` must be set to the Cartesian coordinates of the data point :math:`\left(x_{\textit{r}}, y_{\textit{r}}, z_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,m`.
**z** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{x}[\textit{r}-1]`, :math:`\mathrm{y}[\textit{r}-1]`, :math:`\mathrm{z}[\textit{r}-1]` must be set to the Cartesian coordinates of the data point :math:`\left(x_{\textit{r}}, y_{\textit{r}}, z_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,m`.
**f** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{f}[\textit{r}-1]` must be set to the data value :math:`f_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m`.
**nw** : int
The number :math:`N_w` of data points that determines each radius of influence :math:`R_w`, appearing in the definition of each of the weights :math:`w_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m` (see :ref:`Notes <e01tg-py2-py-notes>`). Note that :math:`R_w` is different for each weight. If :math:`\mathrm{nw}\leq 0` the default value :math:`\mathrm{nw} = \mathrm{min}\left(32, {m-1}\right)` is used instead.
**nq** : int
The number :math:`N_q` of data points to be used in the least squares fit for coefficients defining the nodal functions :math:`q_r\left(x, y, z\right)` (see :ref:`Notes <e01tg-py2-py-notes>`). If :math:`\mathrm{nq}\leq 0` the default value :math:`\mathrm{nq} = \mathrm{min}\left(17, {m-1}\right)` is used instead.
**Returns**
**iq** : int, ndarray, shape :math:`\left(2\times m+1\right)`
Integer data defining the interpolant :math:`Q\left(x, y, z\right)`.
**rq** : float, ndarray, shape :math:`\left(10\times m+7\right)`
Real data defining the interpolant :math:`Q\left(x, y, z\right)`.
.. _e01tg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{lrq}` is too small: :math:`\textit{lrq} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\textit{liq}` is too small: :math:`\textit{liq} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nw}\leq \mathrm{min}\left(40, {m-1}\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nq} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nq}\leq \mathrm{min}\left(40, {m-1}\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nq} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nq} \leq 0` or :math:`\mathrm{nq} \geq 9`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 10`.
(`errno` :math:`2`)
There are duplicate nodes in the dataset. :math:`\left({\mathrm{x}[\textit{I}-1]}, {\mathrm{y}[\textit{I}-1]}, {\mathrm{z}[\textit{I}-1]}\right) = \left({\mathrm{x}[\textit{J}-1]}, {\mathrm{y}[\textit{J}-1]}, {\mathrm{z}[\textit{J}-1]}\right)` for: :math:`\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle`. The interpolant cannot be derived.
(`errno` :math:`3`)
All nodes are coplanar. There is no unique solution.
.. _e01tg-py2-py-notes:
**Notes**
``dim3_scat_shep`` constructs a smooth function :math:`Q\left(x, y, z\right)` which interpolates a set of :math:`m` scattered data points :math:`\left(x_r, y_r, z_r, f_r\right)`, for :math:`r = 1,2,\ldots,m`, using a modification of Shepard's method.
The surface is continuous and has continuous first partial derivatives.
The basic Shepard method, which is a generalization of the two-dimensional method described in Shepard (1968), interpolates the input data with the weighted mean
.. math::
Q\left(x, y, z\right) = \frac{{\sum_{{r = 1}}^mw_r\left(x, y, z\right)q_r}}{{\sum_{{r = 1}}^mw_r\left(x, y, z\right)}}\text{,}
where
.. math::
q_r = f_r\text{ and }w_r\left(x, y, z\right) = \frac{1}{{d_r^2}}\text{ and }d_r^2 = \left(x-x_r\right)^2+\left(y-y_r\right)^2+\left(z-z_r\right)^2\text{.}
The basic method is global in that the interpolated value at any point depends on all the data, but this function uses a modification (see Franke and Nielson (1980) and Renka (1988a)), whereby the method becomes local by adjusting each :math:`w_r\left(x, y, z\right)` to be zero outside a sphere with centre :math:`\left(x_r, y_r, z_r\right)` and some radius :math:`R_w`.
Also, to improve the performance of the basic method, each :math:`q_r` above is replaced by a function :math:`q_r\left(x, y, z\right)`, which is a quadratic fitted by weighted least squares to data local to :math:`\left(x_r, y_r, z_r\right)` and forced to interpolate :math:`\left(x_r, y_r, z_r, f_r\right)`.
In this context, a point :math:`\left(x, y, z\right)` is defined to be local to another point if it lies within some distance :math:`R_q` of it.
Computation of these quadratics constitutes the main work done by this function.
The efficiency of the function is further enhanced by using a cell method for nearest neighbour searching due to Bentley and Friedman (1979).
The radii :math:`R_w` and :math:`R_q` are chosen to be just large enough to include :math:`N_w` and :math:`N_q` data points, respectively, for user-supplied constants :math:`N_w` and :math:`N_q`.
Default values of these arguments are provided by the function, and advice on alternatives is given in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01tgf.html#fcomments2>`__.
This function is derived from the function QSHEP3 described by Renka (1988b).
Values of the interpolant :math:`Q\left(x, y, z\right)` generated by this function, and its first partial derivatives, can subsequently be evaluated for points in the domain of the data by a call to :meth:`dim3_scat_shep_eval`.
.. _e01tg-py2-py-references:
**References**
Bentley, J L and Friedman, J H, 1979, `Data structures for range searching`, ACM Comput. Surv. (11), 397--409
Franke, R and Nielson, G, 1980, `Smooth interpolation of large sets of scattered data`, Internat. J. Num. Methods Engrg. (15), 1691--1704
Renka, R J, 1988, `Multivariate interpolation of large sets of scattered data`, ACM Trans. Math. Software (14), 139--148
Renka, R J, 1988, `Algorithm 661: QSHEP3D: Quadratic Shepard method for trivariate interpolation of scattered data`, ACM Trans. Math. Software (14), 151--152
Shepard, D, 1968, `A two-dimensional interpolation function for irregularly spaced data`, Proc. 23rd Nat. Conf. ACM, 517--523, Brandon/Systems Press Inc., Princeton
"""
raise NotImplementedError
[docs]def dim3_scat_shep_eval(x, y, z, f, iq, rq, u, v, w):
r"""
``dim3_scat_shep_eval`` evaluates the three-dimensional interpolating function generated by :meth:`dim3_scat_shep` and its first partial derivatives.
.. _e01th-py2-py-doc:
For full information please refer to the NAG Library document for e01th
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01thf.html
.. _e01th-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(m\right)`
:math:`\textit{m}`, :math:`\mathrm{x}`, :math:`\mathrm{y}`, :math:`\mathrm{z}` and :math:`\mathrm{f}` must be the same values as were supplied in the preceding call to :meth:`dim3_scat_shep`.
**y** : float, array-like, shape :math:`\left(m\right)`
:math:`\textit{m}`, :math:`\mathrm{x}`, :math:`\mathrm{y}`, :math:`\mathrm{z}` and :math:`\mathrm{f}` must be the same values as were supplied in the preceding call to :meth:`dim3_scat_shep`.
**z** : float, array-like, shape :math:`\left(m\right)`
:math:`\textit{m}`, :math:`\mathrm{x}`, :math:`\mathrm{y}`, :math:`\mathrm{z}` and :math:`\mathrm{f}` must be the same values as were supplied in the preceding call to :meth:`dim3_scat_shep`.
**f** : float, array-like, shape :math:`\left(m\right)`
:math:`\textit{m}`, :math:`\mathrm{x}`, :math:`\mathrm{y}`, :math:`\mathrm{z}` and :math:`\mathrm{f}` must be the same values as were supplied in the preceding call to :meth:`dim3_scat_shep`.
**iq** : int, array-like, shape :math:`\left(2\times m+1\right)`
Must be unchanged from the value returned from a previous call to :meth:`dim3_scat_shep`.
**rq** : float, array-like, shape :math:`\left(10\times m+7\right)`
Must be unchanged from the value returned from a previous call to :meth:`dim3_scat_shep`.
**u** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{u}[\textit{i}-1]`, :math:`\mathrm{v}[\textit{i}-1]`, :math:`\mathrm{w}[\textit{i}-1]` must be set to the evaluation point :math:`\left(u_{\textit{i}}, v_{\textit{i}}, w_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`.
**v** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{u}[\textit{i}-1]`, :math:`\mathrm{v}[\textit{i}-1]`, :math:`\mathrm{w}[\textit{i}-1]` must be set to the evaluation point :math:`\left(u_{\textit{i}}, v_{\textit{i}}, w_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`.
**w** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{u}[\textit{i}-1]`, :math:`\mathrm{v}[\textit{i}-1]`, :math:`\mathrm{w}[\textit{i}-1]` must be set to the evaluation point :math:`\left(u_{\textit{i}}, v_{\textit{i}}, w_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`.
**Returns**
**q** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{q}[\textit{i}-1]` contains the value of the interpolant, at :math:`\left(u_{\textit{i}}, v_{\textit{i}}, w_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`. If any of these evaluation points lie outside the region of definition of the interpolant the corresponding entries in :math:`\mathrm{q}` are set to an extrapolated approximation, and ``dim3_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
**qx** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{qx}[\textit{i}-1]`, :math:`\mathrm{qy}[\textit{i}-1]`, :math:`\mathrm{qz}[\textit{i}-1]` contains the value of the partial derivatives of the interpolant :math:`Q\left(x, y, z\right)` at :math:`\left(u_{\textit{i}}, v_{\textit{i}}, w_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`. If any of these evaluation points lie outside the region of definition of the interpolant, the corresponding entries in :math:`\mathrm{qx}`, :math:`\mathrm{qy}` and :math:`\mathrm{qz}` are set to extrapolated approximations to the partial derivatives, and ``dim3_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
**qy** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{qx}[\textit{i}-1]`, :math:`\mathrm{qy}[\textit{i}-1]`, :math:`\mathrm{qz}[\textit{i}-1]` contains the value of the partial derivatives of the interpolant :math:`Q\left(x, y, z\right)` at :math:`\left(u_{\textit{i}}, v_{\textit{i}}, w_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`. If any of these evaluation points lie outside the region of definition of the interpolant, the corresponding entries in :math:`\mathrm{qx}`, :math:`\mathrm{qy}` and :math:`\mathrm{qz}` are set to extrapolated approximations to the partial derivatives, and ``dim3_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
**qz** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{qx}[\textit{i}-1]`, :math:`\mathrm{qy}[\textit{i}-1]`, :math:`\mathrm{qz}[\textit{i}-1]` contains the value of the partial derivatives of the interpolant :math:`Q\left(x, y, z\right)` at :math:`\left(u_{\textit{i}}, v_{\textit{i}}, w_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`. If any of these evaluation points lie outside the region of definition of the interpolant, the corresponding entries in :math:`\mathrm{qx}`, :math:`\mathrm{qy}` and :math:`\mathrm{qz}` are set to extrapolated approximations to the partial derivatives, and ``dim3_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
.. _e01th-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{lrq}` is too small: :math:`\textit{lrq} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\textit{liq}` is too small: :math:`\textit{liq} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 10`.
(`errno` :math:`2`)
On entry, values in :math:`\mathrm{rq}` appear to be invalid. Check that :math:`\mathrm{rq}` has not been corrupted between calls to :meth:`dim3_scat_shep` and ``dim3_scat_shep_eval``.
(`errno` :math:`2`)
On entry, values in :math:`\mathrm{iq}` appear to be invalid. Check that :math:`\mathrm{iq}` has not been corrupted between calls to :meth:`dim3_scat_shep` and ``dim3_scat_shep_eval``.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
On entry, at least one evaluation point lies outside the region of definition of the interpolant. At such points the corresponding values in :math:`\mathrm{q}` and :math:`\mathrm{qx}` contain extrapolated approximations. Points should be evaluated one by one to identify extrapolated values.
.. _e01th-py2-py-notes:
**Notes**
``dim3_scat_shep_eval`` takes as input the interpolant :math:`Q\left(x, y, z\right)` of a set of scattered data points :math:`\left(x_r, y_r, z_r, f_r\right)`, for :math:`\textit{r} = 1,2,\ldots,m`, as computed by :meth:`dim3_scat_shep`, and evaluates the interpolant and its first partial derivatives at the set of points :math:`\left(u_i, v_i, w_i\right)`, for :math:`\textit{i} = 1,2,\ldots,n`.
``dim3_scat_shep_eval`` must only be called after a call to :meth:`dim3_scat_shep`.
This function is derived from the function QS3GRD described by Renka (1988).
.. _e01th-py2-py-references:
**References**
Renka, R J, 1988, `Algorithm 661: QSHEP3D: Quadratic Shepard method for trivariate interpolation of scattered data`, ACM Trans. Math. Software (14), 151--152
"""
raise NotImplementedError
[docs]def dim4_scat_shep(x, f, nw, nq):
r"""
``dim4_scat_shep`` generates a four-dimensional interpolant to a set of scattered data points, using a modified Shepard method.
.. _e01tk-py2-py-doc:
For full information please refer to the NAG Library document for e01tk
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01tkf.html
.. _e01tk-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(4, m\right)`
:math:`\mathrm{x}[0,\textit{r}-1],\ldots,\mathrm{x}[3,\textit{r}-1]` must be set to the Cartesian coordinates of the data point :math:`\mathbf{x}_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m`.
**f** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{f}[\textit{r}-1]` must be set to the data value :math:`f_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m`.
**nw** : int
The number :math:`N_w` of data points that determines each radius of influence :math:`R_w`, appearing in the definition of each of the weights :math:`w_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m` (see :ref:`Notes <e01tk-py2-py-notes>`). Note that :math:`R_w` is different for each weight. If :math:`\mathrm{nw}\leq 0` the default value :math:`\mathrm{nw} = \mathrm{min}\left(32, {m-1}\right)` is used instead.
**nq** : int
The number :math:`N_q` of data points to be used in the least squares fit for coefficients defining the quadratic functions :math:`q_r\left(\mathbf{x}\right)` (see :ref:`Notes <e01tk-py2-py-notes>`). If :math:`\mathrm{nq}\leq 0` the default value :math:`\mathrm{nq} = \mathrm{min}\left(38, {m-1}\right)` is used instead.
**Returns**
**iq** : int, ndarray, shape :math:`\left(2\times m+1\right)`
Integer data defining the interpolant :math:`Q\left(\mathbf{x}\right)`.
**rq** : float, ndarray, shape :math:`\left(15\times m+9\right)`
Real data defining the interpolant :math:`Q\left(\mathbf{x}\right)`.
.. _e01tk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{nw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nw}\leq \mathrm{min}\left(50, {m-1}\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nq} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nq}\leq \mathrm{min}\left(50, {m-1}\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nq} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nq} \leq 0` or :math:`\mathrm{nq} \geq 14`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 16`.
(`errno` :math:`2`)
There are duplicate nodes in the dataset. :math:`{\mathrm{x}[i-1,k-1]} = {\mathrm{x}[j-1,k-1]}`, for :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`j = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`k = 1,2,\ldots,4`. The interpolant cannot be derived.
(`errno` :math:`3`)
On entry, all the data points lie on the same three-dimensional hypersurface. No unique solution exists.
.. _e01tk-py2-py-notes:
**Notes**
``dim4_scat_shep`` constructs a smooth function :math:`Q\left(\mathbf{x}\right)`, :math:`\mathbf{x} \in \mathbb{R}^4` which interpolates a set of :math:`m` scattered data points :math:`\left(\mathbf{x}_r, f_r\right)`, for :math:`r = 1,2,\ldots,m`, using a modification of Shepard's method.
The surface is continuous and has continuous first partial derivatives.
The basic Shepard method, which is a generalization of the two-dimensional method described in Shepard (1968), interpolates the input data with the weighted mean
.. math::
Q\left(\mathbf{x}\right) = \frac{{\sum_{{r = 1}}^mw_r\left(\mathbf{x}\right)q_r}}{{\sum_{{r = 1}}^mw_r\left(\mathbf{x}\right)}}\text{,}
where :math:`q_r = f_r`, :math:`w_r\left(\mathbf{x}\right) = \frac{1}{{d_r^2}}` and :math:`d_r^2 = \left\lVert \mathbf{x}-\mathbf{x}_r\right\rVert_2^2`.
The basic method is global in that the interpolated value at any point depends on all the data, but ``dim4_scat_shep`` uses a modification (see Franke and Nielson (1980) and Renka (1988a)), whereby the method becomes local by adjusting each :math:`w_r\left(\mathbf{x}\right)` to be zero outside a hypersphere with centre :math:`\mathbf{x}_r` and some radius :math:`R_w`.
Also, to improve the performance of the basic method, each :math:`q_r` above is replaced by a function :math:`q_r\left(\mathbf{x}\right)`, which is a quadratic fitted by weighted least squares to data local to :math:`\mathbf{x}_r` and forced to interpolate :math:`\left(\mathbf{x}_r, f_r\right)`.
In this context, a point :math:`\mathbf{x}` is defined to be local to another point if it lies within some distance :math:`R_q` of it.
The efficiency of ``dim4_scat_shep`` is enhanced by using a cell method for nearest neighbour searching due to Bentley and Friedman (1979) with a cell density of :math:`3`.
The radii :math:`R_w` and :math:`R_q` are chosen to be just large enough to include :math:`N_w` and :math:`N_q` data points, respectively, for user-supplied constants :math:`N_w` and :math:`N_q`.
Default values of these arguments are provided by the function, and advice on alternatives is given in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01tkf.html#fcomments2>`__.
``dim4_scat_shep`` is derived from the new implementation of QSHEP3 described by Renka (1988b).
It uses the modification for high-dimensional interpolation described by Berry and Minser (1999).
Values of the interpolant :math:`Q\left(\mathbf{x}\right)` generated by ``dim4_scat_shep``, and its first partial derivatives, can subsequently be evaluated for points in the domain of the data by a call to :meth:`dim4_scat_shep_eval`.
.. _e01tk-py2-py-references:
**References**
Bentley, J L and Friedman, J H, 1979, `Data structures for range searching`, ACM Comput. Surv. (11), 397--409
Berry, M W, Minser, K S, 1999, `Algorithm 798: high-dimensional interpolation using the modified Shepard method`, ACM Trans. Math. Software (25), 353--366
Franke, R and Nielson, G, 1980, `Smooth interpolation of large sets of scattered data`, Internat. J. Num. Methods Engrg. (15), 1691--1704
Renka, R J, 1988, `Multivariate interpolation of large sets of scattered data`, ACM Trans. Math. Software (14), 139--148
Renka, R J, 1988, `Algorithm 661: QSHEP3D: Quadratic Shepard method for trivariate interpolation of scattered data`, ACM Trans. Math. Software (14), 151--152
Shepard, D, 1968, `A two-dimensional interpolation function for irregularly spaced data`, Proc. 23rd Nat. Conf. ACM, 517--523, Brandon/Systems Press Inc., Princeton
"""
raise NotImplementedError
[docs]def dim4_scat_shep_eval(x, f, iq, rq, xe):
r"""
``dim4_scat_shep_eval`` evaluates the four-dimensional interpolating function generated by :meth:`dim4_scat_shep` and its first partial derivatives.
.. _e01tl-py2-py-doc:
For full information please refer to the NAG Library document for e01tl
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01tlf.html
.. _e01tl-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(4, m\right)`
Note: the coordinates of :math:`x_r` are stored in :math:`\mathrm{x}[0,r-1]\ldots \mathrm{x}[3,r-1]`.
**Must** be the same array supplied as argument :math:`\textit{x}` in the preceding call to :meth:`dim4_scat_shep`. It **must** remain unchanged between calls.
**f** : float, array-like, shape :math:`\left(m\right)`
**Must** be the same array supplied as argument :math:`\textit{f}` in the preceding call to :meth:`dim4_scat_shep`. It **must** remain unchanged between calls.
**iq** : int, array-like, shape :math:`\left(2\times m+1\right)`
**Must** be the same array returned as argument :math:`\textit{iq}` in the preceding call to :meth:`dim4_scat_shep`. It **must** remain unchanged between calls.
**rq** : float, array-like, shape :math:`\left(15\times m+9\right)`
**Must** be the same array returned as argument :math:`\textit{rq}` in the preceding call to :meth:`dim4_scat_shep`. It **must** remain unchanged between calls.
**xe** : float, array-like, shape :math:`\left(4, n\right)`
:math:`\mathrm{xe}[0,\textit{r}-1],\ldots,\mathrm{xe}[3,\textit{r}-1]` must be set to the evaluation point :math:`\mathbf{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
**Returns**
**q** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{q}[\textit{i}-1]` contains the value of the interpolant, at :math:`\mathbf{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`. If any of these evaluation points lie outside the region of definition of the interpolant the corresponding entries in :math:`\mathrm{q}` are set to an extrapolated approximation, and ``dim4_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
**qx** : float, ndarray, shape :math:`\left(4, n\right)`
:math:`\mathrm{qx}[j-1,i-1]` contains the value of the partial derivatives with respect to :math:`\mathbf{x}_j` of the interpolant :math:`Q\left(\mathbf{x}\right)` at :math:`\mathbf{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`, and for each of the four partial derivatives :math:`j = 1,2,3,4`. If any of these evaluation points lie outside the region of definition of the interpolant, the corresponding entries in :math:`\mathrm{qx}` are set to extrapolated approximations to the partial derivatives, and ``dim4_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
.. _e01tl-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 16`.
(`errno` :math:`2`)
On entry, values in :math:`\mathrm{rq}` appear to be invalid. Check that :math:`\mathrm{rq}` has not been corrupted between calls to :meth:`dim4_scat_shep` and ``dim4_scat_shep_eval``.
(`errno` :math:`2`)
On entry, values in :math:`\mathrm{iq}` appear to be invalid. Check that :math:`\mathrm{iq}` has not been corrupted between calls to :meth:`dim4_scat_shep` and ``dim4_scat_shep_eval``.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
On entry, at least one evaluation point lies outside the region of definition of the interpolant. At such points the corresponding values in :math:`\mathrm{q}` and :math:`\mathrm{qx}` contain extrapolated approximations. Points should be evaluated one by one to identify extrapolated values.
.. _e01tl-py2-py-notes:
**Notes**
``dim4_scat_shep_eval`` takes as input the interpolant :math:`Q\left(\mathbf{x}\right)`, :math:`x \in \mathbb{R}^4` of a set of scattered data points :math:`\left(\mathbf{x}_{\textit{r}}, f_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,m`, as computed by :meth:`dim4_scat_shep`, and evaluates the interpolant and its first partial derivatives at the set of points :math:`\mathbf{x}_i`, for :math:`\textit{i} = 1,2,\ldots,n`.
``dim4_scat_shep_eval`` must only be called after a call to :meth:`dim4_scat_shep`.
``dim4_scat_shep_eval`` is derived from the new implementation of QS3GRD described by Renka (1988).
It uses the modification for high-dimensional interpolation described by Berry and Minser (1999).
.. _e01tl-py2-py-references:
**References**
Berry, M W, Minser, K S, 1999, `Algorithm 798: high-dimensional interpolation using the modified Shepard method`, ACM Trans. Math. Software (25), 353--366
Renka, R J, 1988, `Algorithm 661: QSHEP3D: Quadratic Shepard method for trivariate interpolation of scattered data`, ACM Trans. Math. Software (14), 151--152
"""
raise NotImplementedError
[docs]def dim5_scat_shep(x, f, nw, nq):
r"""
``dim5_scat_shep`` generates a five-dimensional interpolant to a set of scattered data points, using a modified Shepard method.
.. _e01tm-py2-py-doc:
For full information please refer to the NAG Library document for e01tm
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01tmf.html
.. _e01tm-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(5, m\right)`
:math:`\mathrm{x}[0,\textit{r}-1],\ldots,\mathrm{x}[4,\textit{r}-1]` must be set to the Cartesian coordinates of the data point :math:`\mathbf{x}_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m`.
**f** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{f}[\textit{r}-1]` must be set to the data value :math:`f_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m`.
**nw** : int
The number :math:`N_w` of data points that determines each radius of influence :math:`R_w`, appearing in the definition of each of the weights :math:`w_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m` (see :ref:`Notes <e01tm-py2-py-notes>`). Note that :math:`R_w` is different for each weight. If :math:`\mathrm{nw}\leq 0` the default value :math:`\mathrm{nw} = \mathrm{min}\left(32, {m-1}\right)` is used instead.
**nq** : int
The number :math:`N_q` of data points to be used in the least squares fit for coefficients defining the quadratic functions :math:`q_r\left(\mathbf{x}\right)` (see :ref:`Notes <e01tm-py2-py-notes>`). If :math:`\mathrm{nq}\leq 0` the default value :math:`\mathrm{nq} = \mathrm{min}\left(50, {m-1}\right)` is used instead.
**Returns**
**iq** : int, ndarray, shape :math:`\left(2\times m+1\right)`
Integer data defining the interpolant :math:`Q\left(\mathbf{x}\right)`.
**rq** : float, ndarray, shape :math:`\left(21\times m+11\right)`
Real data defining the interpolant :math:`Q\left(\mathbf{x}\right)`.
.. _e01tm-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{nw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nw}\leq \mathrm{min}\left(50, {m-1}\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nq} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nq}\leq \mathrm{min}\left(70, {m-1}\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nq} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nq} \leq 0` or :math:`\mathrm{nq} \geq 20`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 23`.
(`errno` :math:`2`)
There are duplicate nodes in the dataset. :math:`{\mathrm{x}[i-1,k-1]} = {\mathrm{x}[j-1,k-1]}`, for :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`j = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`k = 1,2,\ldots,5`. The interpolant cannot be derived.
(`errno` :math:`3`)
On entry, all the data points lie on the same four-dimensional hypersurface. No unique solution exists.
.. _e01tm-py2-py-notes:
**Notes**
``dim5_scat_shep`` constructs a smooth function :math:`Q\left(\mathbf{x}\right)`, :math:`\mathbf{x} \in \mathbb{R}^5` which interpolates a set of :math:`m` scattered data points :math:`\left(\mathbf{x}_r, f_r\right)`, for :math:`r = 1,2,\ldots,m`, using a modification of Shepard's method.
The surface is continuous and has continuous first partial derivatives.
The basic Shepard method, which is a generalization of the two-dimensional method described in Shepard (1968), interpolates the input data with the weighted mean
.. math::
Q\left(\mathbf{x}\right) = \frac{{\sum_{{r = 1}}^mw_r\left(\mathbf{x}\right)q_r}}{{\sum_{{r = 1}}^mw_r\left(\mathbf{x}\right)}}\text{,}
where :math:`q_r = f_r`, :math:`w_r\left(\mathbf{x}\right) = \frac{1}{{d_r^2}}` and :math:`d_r^2 = \left\lVert \mathbf{x}-\mathbf{x}_r\right\rVert_2^2`.
The basic method is global in that the interpolated value at any point depends on all the data, but ``dim5_scat_shep`` uses a modification (see Franke and Nielson (1980) and Renka (1988a)), whereby the method becomes local by adjusting each :math:`w_r\left(\mathbf{x}\right)` to be zero outside a hypersphere with centre :math:`\mathbf{x}_r` and some radius :math:`R_w`.
Also, to improve the performance of the basic method, each :math:`q_r` above is replaced by a function :math:`q_r\left(\mathbf{x}\right)`, which is a quadratic fitted by weighted least squares to data local to :math:`\mathbf{x}_r` and forced to interpolate :math:`\left(\mathbf{x}_r, f_r\right)`.
In this context, a point :math:`\mathbf{x}` is defined to be local to another point if it lies within some distance :math:`R_q` of it.
The efficiency of ``dim5_scat_shep`` is enhanced by using a cell method for nearest neighbour searching due to Bentley and Friedman (1979) with a cell density of :math:`3`.
The radii :math:`R_w` and :math:`R_q` are chosen to be just large enough to include :math:`N_w` and :math:`N_q` data points, respectively, for user-supplied constants :math:`N_w` and :math:`N_q`.
Default values of these arguments are provided, and advice on alternatives is given in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01tmf.html#fcomments2>`__.
``dim5_scat_shep`` is derived from the new implementation of QSHEP3 described by Renka (1988b).
It uses the modification for five-dimensional interpolation described by Berry and Minser (1999).
Values of the interpolant :math:`Q\left(\mathbf{x}\right)` generated by ``dim5_scat_shep``, and its first partial derivatives, can subsequently be evaluated for points in the domain of the data by a call to :meth:`dim5_scat_shep_eval`.
.. _e01tm-py2-py-references:
**References**
Bentley, J L and Friedman, J H, 1979, `Data structures for range searching`, ACM Comput. Surv. (11), 397--409
Berry, M W, Minser, K S, 1999, `Algorithm 798: high-dimensional interpolation using the modified Shepard method`, ACM Trans. Math. Software (25), 353--366
Franke, R and Nielson, G, 1980, `Smooth interpolation of large sets of scattered data`, Internat. J. Num. Methods Engrg. (15), 1691--1704
Renka, R J, 1988, `Multivariate interpolation of large sets of scattered data`, ACM Trans. Math. Software (14), 139--148
Renka, R J, 1988, `Algorithm 661: QSHEP3D: Quadratic Shepard method for trivariate interpolation of scattered data`, ACM Trans. Math. Software (14), 151--152
Shepard, D, 1968, `A two-dimensional interpolation function for irregularly spaced data`, Proc. 23rd Nat. Conf. ACM, 517--523, Brandon/Systems Press Inc., Princeton
"""
raise NotImplementedError
[docs]def dim5_scat_shep_eval(x, f, iq, rq, xe):
r"""
``dim5_scat_shep_eval`` evaluates the five-dimensional interpolating function generated by :meth:`dim5_scat_shep` and its first partial derivatives.
.. _e01tn-py2-py-doc:
For full information please refer to the NAG Library document for e01tn
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01tnf.html
.. _e01tn-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(5, m\right)`
**Must** be the same array supplied as argument :math:`\textit{x}` in the preceding call to :meth:`dim5_scat_shep`. It **must** remain unchanged between calls.
**f** : float, array-like, shape :math:`\left(m\right)`
**Must** be the same array supplied as argument :math:`\textit{f}` in the preceding call to :meth:`dim5_scat_shep`. It **must** remain unchanged between calls.
**iq** : int, array-like, shape :math:`\left(2\times m+1\right)`
**Must** be the same array returned as argument :math:`\textit{iq}` in the preceding call to :meth:`dim5_scat_shep`. It **must** remain unchanged between calls.
**rq** : float, array-like, shape :math:`\left(21\times m+11\right)`
**Must** be the same array returned as argument :math:`\textit{rq}` in the preceding call to :meth:`dim5_scat_shep`. It **must** remain unchanged between calls.
**xe** : float, array-like, shape :math:`\left(5, n\right)`
:math:`\mathrm{xe}[0,\textit{i}-1],\ldots,\mathrm{xe}[4,\textit{i}-1]` must be set to the evaluation point :math:`\mathbf{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
**Returns**
**q** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{q}[\textit{i}-1]` contains the value of the interpolant, at :math:`\mathbf{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`. If any of these evaluation points lie outside the region of definition of the interpolant the corresponding entries in :math:`\mathrm{q}` are set to an extrapolated approximation, and ``dim5_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
**qx** : float, ndarray, shape :math:`\left(5, n\right)`
:math:`\mathrm{qx}[j-1,i-1]` contains the value of the partial derivatives with respect to :math:`\mathbf{x}_j` of the interpolant :math:`Q\left(\mathbf{x}\right)` at :math:`\mathbf{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`, and for each of the five partial derivatives :math:`j = 1,2,3,4,5`. If any of these evaluation points lie outside the region of definition of the interpolant, the corresponding entries in :math:`\mathrm{qx}` are set to extrapolated approximations to the partial derivatives, and ``dim5_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
.. _e01tn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 23`.
(`errno` :math:`2`)
On entry, values in :math:`\mathrm{rq}` appear to be invalid. Check that :math:`\mathrm{rq}` has not been corrupted between calls to :meth:`dim5_scat_shep` and ``dim5_scat_shep_eval``.
(`errno` :math:`2`)
On entry, values in :math:`\mathrm{iq}` appear to be invalid. Check that :math:`\mathrm{iq}` has not been corrupted between calls to :meth:`dim5_scat_shep` and ``dim5_scat_shep_eval``.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
On entry, at least one evaluation point lies outside the region of definition of the interpolant. At such points the corresponding values in :math:`\mathrm{q}` and :math:`\mathrm{qx}` contain extrapolated approximations. Points should be evaluated one by one to identify extrapolated values.
.. _e01tn-py2-py-notes:
**Notes**
``dim5_scat_shep_eval`` takes as input the interpolant :math:`Q\left(\mathbf{x}\right)`, :math:`\mathbf{x} \in \mathbb{R}^5` of a set of scattered data points :math:`\left(\mathbf{x}_{\textit{r}}, f_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,m`, as computed by :meth:`dim5_scat_shep`, and evaluates the interpolant and its first partial derivatives at the set of points :math:`\mathbf{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
``dim5_scat_shep_eval`` must only be called after a call to :meth:`dim5_scat_shep`.
``dim5_scat_shep_eval`` is derived from the new implementation of QS3GRD described by Renka (1988).
It uses the modification for five-dimensional interpolation described by Berry and Minser (1999).
.. _e01tn-py2-py-references:
**References**
Berry, M W, Minser, K S, 1999, `Algorithm 798: high-dimensional interpolation using the modified Shepard method`, ACM Trans. Math. Software (25), 353--366
Renka, R J, 1988, `Algorithm 661: QSHEP3D: Quadratic Shepard method for trivariate interpolation of scattered data`, ACM Trans. Math. Software (14), 151--152
"""
raise NotImplementedError
[docs]def dimn_grid(narr, uniform, axis, v, point, method, k=1, wf=0.0):
r"""
``dimn_grid`` interpolates data at a point in :math:`n`-dimensional space, that is defined by a set of gridded data points.
It offers three methods to interpolate the data: Linear Interpolation, Cubic Interpolation and Weighted Average.
.. _e01za-py2-py-doc:
For full information please refer to the NAG Library document for e01za
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01zaf.html
.. _e01za-py2-py-parameters:
**Parameters**
**narr** : int, array-like, shape :math:`\left(d\right)`
The number of data ordinates in each dimension, with :math:`\mathrm{narr}[\textit{i}-1] = n_i`, for :math:`\textit{i} = 1,2,\ldots,d`.
**uniform** : bool
States whether the data points are uniformly spaced.
:math:`\mathrm{uniform} = \mathbf{True}`
The data points are uniformly spaced.
:math:`\mathrm{uniform} = \mathbf{False}`
The data points are not uniformly spaced.
**axis** : float, array-like, shape :math:`\left(\textit{lx}\right)`
Defines the axis. If the data points are uniformly spaced (see argument :math:`\mathrm{uniform}`) :math:`\mathrm{axis}` should contain the start and end of each dimension :math:`\left(x_{{1 1}}, x_{{1 n_1}}, \ldots, x_{{d 1}}, x_{{d n_d}}\right)`.
If the data points are not uniformly spaced, :math:`\mathrm{axis}` should contain all the data ordinates for each dimension :math:`\left(x_{{1 1}}, x_{{1 2}}, \ldots, x_{{1 n_1}}, \ldots, x_{{d 1}}, x_{{d 2}}, \ldots, x_{{d n_d}}\right)`.
**v** : float, array-like, shape :math:`\left(\mathrm{prod}\left(\mathrm{narr}\right)\right)`
Holds the values of the data points in such an order that the index of a data value with coordinates :math:`\left(z_1, z_2, \ldots, z_d\right)` is
.. math::
\sum_{1}^{d}{z_{\textit{i}}\prod_{{n \in \mathbf{S}_i}}n}\text{,}
where :math:`\mathbf{S}_i = \left\{\mathrm{narr}[l-1]:l = \left. 1, \ldots, {i-1}\right. \right\}` e.g., :math:`\left(\left(x_{{11}}, x_{{21}}, \ldots, x_{{d1}}\right), \left(x_{{12}}, x_{{21}}, \ldots, x_{{d1}}\right), \ldots, \left(x_{{1n_d}}, x_{{21}}, \ldots, x_{{d1}}\right), \left(x_{{11}}, x_{{22}}, \ldots, x_{{d1}}\right), \left(x_{{12}}, x_{{22}}, \ldots, x_{{d1}}\right), \ldots, \left(x_{{1n_d}}, x_{{2n_d}}, \ldots, x_{{dn_d}}\right)\right)`.
**point** : float, array-like, shape :math:`\left(d\right)`
:math:`\mathbf{x}`, the point at which the data value is to be interpolated.
**method** : int
The method to be used.
:math:`\mathrm{method} = 1`
Weighted Average.
:math:`\mathrm{method} = 2`
Linear Interpolation.
:math:`\mathrm{method} = 3`
Cubic Interpolation.
**k** : int, optional
If :math:`\mathrm{method} = 1`, :math:`\mathrm{k}` controls the number of data points used in the Weighted Average method, with :math:`\mathrm{k}` points used in each dimension, either side of the interpolation point. The total number of data points used for the interpolation will, therefore, be :math:`\left(2\mathrm{k}\right)^d`.
If :math:`\mathrm{method} \neq 1`, then :math:`\mathrm{k}` is not referenced and need not be set.
**wf** : float, optional
The power used for the weighted average such that a high power will cause closer points to be more heavily weighted.
**Returns**
**ans** : float
Holds the result of the interpolation.
.. _e01za-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`d = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`d\geq 2`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{narr}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{narr}[\textit{i}-1]\geq 2`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{axis}` decreases in dimension :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{axis}` definition must be strictly increasing.
(`errno` :math:`5`)
On entry, :math:`\textit{lx} = \langle\mathit{\boldsymbol{value}}\rangle`, sum of :math:`\mathrm{narr}`:math:`= \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{uniform} = \mathbf{False}`, :math:`\textit{lx} =` sum of :math:`\mathrm{narr}`.
(`errno` :math:`5`)
On entry, :math:`\textit{lx} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`d = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{uniform} = \mathbf{True}`, :math:`\textit{lx} = 2d`.
(`errno` :math:`7`)
On entry, :math:`\mathrm{k} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{method} = 1`, :math:`\mathrm{k}\geq 1`.
(`errno` :math:`8`)
On entry, :math:`\mathrm{point}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle` and data range :math:`= \left[\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right]`.
Constraint: :math:`\mathrm{point}` must be within the data range.
(`errno` :math:`9`)
On entry, :math:`\mathrm{method} = 3` and :math:`\mathrm{uniform} = \mathbf{False}`.
Constraint: if :math:`\mathrm{method} = 3`, :math:`\mathrm{uniform}` must be :math:`\mathbf{True}`.
(`errno` :math:`9`)
On entry, :math:`\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{method} = 1`, :math:`2` or :math:`3`.
(`errno` :math:`10`)
On entry, :math:`\mathrm{wf} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{method} = 1`, :math:`1.0\leq \mathrm{wf}\leq 15.0`.
(`errno` :math:`101`)
Cubic Interpolation method does not have enough data surrounding :math:`\mathrm{point}`; interpolation not possible.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`201`)
Warning: the size of :math:`\mathrm{k}` has been reduced, due to too few data points around :math:`\mathrm{point}`.
.. _e01za-py2-py-notes:
**Notes**
``dimn_grid`` interpolates an :math:`n`-dimensional point within a set of gridded data points, :math:`\mathbf{Z} = \left\{z_{{1j_1}}, z_{{2j_2}}, \ldots, z_{{dj_d}}\right\}`, with corresponding data values :math:`\mathbf{F} = \left\{f_{{1j_1}}, f_{{2j_2}}, \ldots, f_{{dj_d}}\right\}` where, for the :math:`i`\ th dimension, :math:`j_i = 1,\ldots,n_i` and :math:`n_i` is the number of ordinates in the :math:`i`\ th dimension.
A hypercube of :math:`\left(2k\right)^d` data points :math:`\left[\mathbf{h}_1, \mathbf{h}_2, \ldots, \mathbf{h}_{{\left(2k\right)^d}}\right]⊂\mathbf{Z}`, where :math:`\mathbf{h}_i = \left(h_{{i1}}, h_{{i2}}, \ldots, h_{{id}}\right)` and the corresponding data values are :math:`f\left(\mathbf{h}_i\right) \in \mathbf{F}`, around the given point, :math:`\mathbf{x} = \left(x_1, x_2, \ldots, x_d\right)`, is found and then used to interpolate using one of the following three methods.
(i) Weighted Average, that is a modification of Shepard's method (Shepard (1968)) as used for scattered data in :meth:`dimn_scat_shep`. This method interpolates the data with the weighted mean
.. math::
Q\left(\mathbf{x}\right) = \frac{{\sum_{{r = 1}}^{\left(2k\right)^d}w_r\left(\mathbf{x}\right)f_r}}{{\sum_{{r = 1}}^{\left(2k\right)^d}w_r\left(\mathbf{x}\right)}}\text{,}
where :math:`f_r = f\left(\mathbf{h}_r\right)`, :math:`w_r\left(\mathbf{x}\right) = \frac{1}{{D\left(\left\lvert \mathbf{x}-\mathbf{h}_r\right\rvert \right)}}` and :math:`D\left(\mathbf{y}\right) = \left. y_1^{\rho }+y_2^{\rho } + \cdots +y_d^{\rho }\right.`, for a given value of :math:`\rho`.
(#) Linear Interpolation, which takes :math:`2^d` surrounding data points (:math:`k = 1`) and performs two one-dimensional linear interpolations in each dimension on data points :math:`\mathbf{h}_a` and :math:`\mathbf{h}_b`, reducing the dimension every iteration until it has reached an answer. The formula for linear interpolation in dimension :math:`i` is simply
.. math::
f = f_a+\left(x_i-h_{{ai}}\right)\frac{{f_b-f_a}}{{h_{{bi}}-h_{{ai}}}}\text{,}
where :math:`f_r = f\left(\mathbf{h}_r\right)` and :math:`h_{{ai}} < x_i < h_{{bi}}`.
(#) Cubic Interpolation, based on cubic convolution (Keys (1981)). In a similar way to the Linear Interpolation method, it performs the interpolations in one dimension reducing it each time, however it requires four surrounding data points in each dimension (:math:`k = 2`), two in each direction :math:`\left(\mathbf{h}_{-1}, \mathbf{h}_0, \mathbf{h}_1, \mathbf{h}_2\right)`. The following is used to calculate the one-dimensional interpolant in dimension :math:`i`
.. math::
f = \frac{1}{2}\begin{pmatrix}1&t&t^2&t^3\end{pmatrix}\begin{pmatrix}0&2&0&0\\-1&0&1&0\\2&-5&4&-1\\-1&3&-3&1\end{pmatrix}\begin{pmatrix}f_{-1}\\f_0\\f_1\\f_2\end{pmatrix}
where :math:`t = x_i-h_{{0i}}` and :math:`f_r = f\left(\mathbf{h}_r\right)`.
.. _e01za-py2-py-references:
**References**
Keys, R, 1981, `Cubic Convolution Interpolation for Digital Image Processing`, IEEE Transactions on Acoutstics, Speech, and Signal Processing (Vol ASSP-29 No. 6), 1153--1160, http://hmi.stanford.edu/doc/Tech_Notes/HMI-TN-2004-004-Interpolation/Keys_cubic_interp.pdf
Shepard, D, 1968, `A two-dimensional interpolation function for irregularly spaced data`, Proc. 23rd Nat. Conf. ACM, 517--523, Brandon/Systems Press Inc., Princeton
"""
raise NotImplementedError
[docs]def dimn_scat_shep(x, f, nw=-1, nq=-1):
r"""
``dimn_scat_shep`` generates a multidimensional interpolant to a set of scattered data points, using a modified Shepard method.
When the number of dimensions is no more than five, there are corresponding functions in submodule ``interp`` which are specific to the given dimensionality. :meth:`dim2_scat_shep` generates the two-dimensional interpolant, while :meth:`dim3_scat_shep`, :meth:`dim4_scat_shep` and :meth:`dim5_scat_shep` generate the three-, four - and five-dimensional interpolants respectively.
.. _e01zm-py2-py-doc:
For full information please refer to the NAG Library document for e01zm
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01zmf.html
.. _e01zm-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(d, m\right)`
The :math:`\textit{d}` components of the first data point must be stored in elements :math:`0,1,\ldots,d-1` of :math:`\mathrm{x}`. The second data point must be stored in elements :math:`d,d+1,\ldots,2\times d-1` of :math:`\mathrm{x}`, and so on. In general, the :math:`\textit{m}` data points must be stored in :math:`\mathrm{x}[\textit{j},\textit{i}]`, for :math:`\textit{j} = 0,1,\ldots,d-1`, for :math:`\textit{i} = 0,1,\ldots,m-1`.
**f** : float, array-like, shape :math:`\left(m\right)`
:math:`\mathrm{f}[r-1]` must be set to the data value :math:`f_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m`.
**nw** : int, optional
The number :math:`N_w` of data points that determines each radius of influence :math:`R_w`, appearing in the definition of each of the weights :math:`w_{\textit{r}}`, for :math:`\textit{r} = 1,2,\ldots,m` (see :ref:`Notes <e01zm-py2-py-notes>`). Note that :math:`R_w` is different for each weight. If :math:`\mathrm{nw}\leq 0` the default value :math:`\mathrm{nw} = \mathrm{min}\left({2\times \left(d+1\right)\times \left(d+2\right)}, {m-1}\right)` is used instead.
**nq** : int, optional
The number :math:`N_q` of data points to be used in the least squares fit for coefficients defining the quadratic functions :math:`q_r\left(\mathbf{x}\right)` (see :ref:`Notes <e01zm-py2-py-notes>`). If :math:`\mathrm{nq}\leq 0` the default value :math:`\mathrm{nq} = \mathrm{min}\left({\left(d+1\right)\times \left(d+2\right)\times 6/5}, {m-1}\right)` is used instead.
**Returns**
**iq** : int, ndarray, shape :math:`\left(2\times m+1\right)`
Integer data defining the interpolant :math:`Q\left(\mathbf{x}\right)`.
**rq** : float, ndarray, shape :math:`\left(\textit{lrq}\right)`
Real data defining the interpolant :math:`Q\left(\mathbf{x}\right)`.
.. _e01zm-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{nw} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nw}\leq m-1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nq} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nq}\leq m-1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nq} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`d = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nq}\leq 0` or :math:`\mathrm{nq}\geq \left(d+1\right)\times \left(d+2\right)/2-1`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`d = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq \left(d+1\right)\times \left(d+2\right)/2+2`.
(`errno` :math:`1`)
On entry, :math:`\left(\left(d+1\right)\times \left(d+2\right)/2\right)\times m+2\times d+1` exceeds the largest machine integer.
:math:`d = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`d = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`d\geq 2`.
(`errno` :math:`2`)
There are duplicate nodes in the dataset. :math:`{\mathrm{x}[k-1,i-1]} = {\mathrm{x}[k-1,j-1]}`, for :math:`i = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`j = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`k = 1,2,\ldots,d`. The interpolant cannot be derived.
(`errno` :math:`3`)
On entry, all the data points lie on the same hypersurface. No unique solution exists.
.. _e01zm-py2-py-notes:
**Notes**
``dimn_scat_shep`` constructs a smooth function :math:`Q\left(\mathbf{x}\right)`, :math:`\mathbf{x} \in \mathbb{R}^d` which interpolates a set of :math:`m` scattered data points :math:`\left(\mathbf{x}_r, f_r\right)`, for :math:`r = 1,2,\ldots,m`, using a modification of Shepard's method.
The surface is continuous and has continuous first partial derivatives.
The basic Shepard method, which is a generalization of the two-dimensional method described in Shepard (1968), interpolates the input data with the weighted mean
.. math::
Q\left(\mathbf{x}\right) = \frac{{\sum_{{r = 1}}^mw_r\left(\mathbf{x}\right)q_r}}{{\sum_{{r = 1}}^mw_r\left(\mathbf{x}\right)}}\text{,}
where :math:`q_r = f_r`, :math:`w_r\left(\mathbf{x}\right) = \frac{1}{\left\lVert \mathbf{x}-\mathbf{x}_r\right\rVert_2^2}`.
The basic method is global in that the interpolated value at any point depends on all the data, but ``dimn_scat_shep`` uses a modification (see Franke and Nielson (1980) and Renka (1988a)), whereby the method becomes local by adjusting each :math:`w_r\left(\mathbf{x}\right)` to be zero outside a hypersphere with centre :math:`\mathbf{x}_r` and some radius :math:`R_w`.
Also, to improve the performance of the basic method, each :math:`q_r` above is replaced by a function :math:`q_r\left(\mathbf{x}\right)`, which is a quadratic fitted by weighted least squares to data local to :math:`\mathbf{x}_r` and forced to interpolate :math:`\left(\mathbf{x}_r, f_r\right)`.
In this context, a point :math:`\mathbf{x}` is defined to be local to another point if it lies within some distance :math:`R_q` of it.
The efficiency of ``dimn_scat_shep`` is enhanced by using a cell method for nearest neighbour searching due to Bentley and Friedman (1979) with a cell density of :math:`3`.
The radii :math:`R_w` and :math:`R_q` are chosen to be just large enough to include :math:`N_w` and :math:`N_q` data points, respectively, for user-supplied constants :math:`N_w` and :math:`N_q`.
Default values of these parameters are provided, and advice on alternatives is given in `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01zmf.html#fcomments2>`__.
``dimn_scat_shep`` is derived from the new implementation of QSHEP3 described by Renka (1988b).
It uses the modification for high-dimensional interpolation described by Berry and Minser (1999).
Values of the interpolant :math:`Q\left(\mathbf{x}\right)` generated by ``dimn_scat_shep``, and its first partial derivatives, can subsequently be evaluated for points in the domain of the data by a call to :meth:`dimn_scat_shep_eval`.
.. _e01zm-py2-py-references:
**References**
Bentley, J L and Friedman, J H, 1979, `Data structures for range searching`, ACM Comput. Surv. (11), 397--409
Berry, M W, Minser, K S, 1999, `Algorithm 798: high-dimensional interpolation using the modified Shepard method`, ACM Trans. Math. Software (25), 353--366
Franke, R and Nielson, G, 1980, `Smooth interpolation of large sets of scattered data`, Internat. J. Num. Methods Engrg. (15), 1691--1704
Renka, R J, 1988, `Multivariate interpolation of large sets of scattered data`, ACM Trans. Math. Software (14), 139--148
Renka, R J, 1988, `Algorithm 661: QSHEP3D: Quadratic Shepard method for trivariate interpolation of scattered data`, ACM Trans. Math. Software (14), 151--152
Shepard, D, 1968, `A two-dimensional interpolation function for irregularly spaced data`, Proc. 23rd Nat. Conf. ACM, 517--523, Brandon/Systems Press Inc., Princeton
"""
raise NotImplementedError
[docs]def dimn_scat_shep_eval(x, f, iq, rq, xe):
r"""
``dimn_scat_shep_eval`` evaluates the multidimensional interpolating function generated by :meth:`dimn_scat_shep` and its first partial derivatives.
.. _e01zn-py2-py-doc:
For full information please refer to the NAG Library document for e01zn
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e01/e01znf.html
.. _e01zn-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(d, m\right)`
Note: the :math:`i`\ th ordinate of the point :math:`x_j` is stored in :math:`\mathrm{x}[i-1,j-1]`.
**Must** be the same array supplied as argument :math:`\textit{x}` in the preceding call to :meth:`dimn_scat_shep`. It **must** remain unchanged between calls.
**f** : float, array-like, shape :math:`\left(m\right)`
**Must** be the same array supplied as argument :math:`\textit{f}` in the preceding call to :meth:`dimn_scat_shep`. It **must** remain unchanged between calls.
**iq** : int, array-like, shape :math:`\left(2\times m+1\right)`
**Must** be the same array returned as argument :math:`\textit{iq}` in the preceding call to :meth:`dimn_scat_shep`. It **must** remain unchanged between calls.
**rq** : float, array-like, shape :math:`\left(\textit{lrq}\right)`
**Must** be the same array returned as argument :math:`\textit{rq}` in the preceding call to :meth:`dimn_scat_shep`. It **must** remain unchanged between calls.
**xe** : float, array-like, shape :math:`\left(d, n\right)`
Note: the :math:`i`\ th ordinate of the point :math:`x_j` is stored in :math:`\mathrm{xe}[i-1,j-1]`.
:math:`\mathrm{xe}[0,\textit{j}-1],\ldots,\mathrm{xe}[d-1,\textit{j}-1]` must be set to the evaluation point :math:`\mathbf{x}_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,n`.
**Returns**
**q** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{q}[\textit{i}-1]` contains the value of the interpolant, at :math:`\mathbf{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`. If any of these evaluation points lie outside the region of definition of the interpolant the corresponding entries in :math:`\mathrm{q}` are set to an extrapolated approximation, and ``dimn_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
**qx** : float, ndarray, shape :math:`\left(d, n\right)`
:math:`\mathrm{qx}[i-1,j-1]` contains the value of the partial derivatives with respect to the :math:`i`\ th independent variable (dimension) of the interpolant :math:`Q\left(\mathbf{x}\right)` at :math:`\mathbf{x}_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,n`, and for each of the partial derivatives :math:`i = 1,2,\ldots,d`. If any of these evaluation points lie outside the region of definition of the interpolant, the corresponding entries in :math:`\mathrm{qx}` are set to extrapolated approximations to the partial derivatives, and ``dimn_scat_shep_eval`` returns with :math:`\mathrm{errno}` = 3.
.. _e01zn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`d = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq \left(d+1\right)\times \left(d+2\right)/2+2`.
(`errno` :math:`1`)
On entry, :math:`\left(\left(d+1\right)\times \left(d+2\right)/2\right)\times m+2\times d+1` exceeds the largest machine integer.
:math:`d = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`d = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`d\geq 2`.
(`errno` :math:`2`)
On entry, values in :math:`\mathrm{rq}` appear to be invalid. Check that :math:`\mathrm{rq}` has not been corrupted between calls to :meth:`dimn_scat_shep` and ``dimn_scat_shep_eval``.
(`errno` :math:`2`)
On entry, values in :math:`\mathrm{iq}` appear to be invalid. Check that :math:`\mathrm{iq}` has not been corrupted between calls to :meth:`dimn_scat_shep` and ``dimn_scat_shep_eval``.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
On entry, at least one evaluation point lies outside the region of definition of the interpolant. At such points the corresponding values in :math:`\mathrm{q}` and :math:`\mathrm{qx}` contain extrapolated approximations. Points should be evaluated one by one to identify extrapolated values.
.. _e01zn-py2-py-notes:
**Notes**
``dimn_scat_shep_eval`` takes as input the interpolant :math:`Q\left(\mathbf{x}\right)`, :math:`\mathbf{x} \in \mathbb{R}^d` of a set of scattered data points :math:`\left(\mathbf{x}_{\textit{r}}, f_{\textit{r}}\right)`, for :math:`\textit{r} = 1,2,\ldots,m`, as computed by :meth:`dimn_scat_shep`, and evaluates the interpolant and its first partial derivatives at the set of points :math:`\mathbf{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
``dimn_scat_shep_eval`` must only be called after a call to :meth:`dimn_scat_shep`.
``dimn_scat_shep_eval`` is derived from the new implementation of QS3GRD described by Renka (1988).
It uses the modification for high-dimensional interpolation described by Berry and Minser (1999).
.. _e01zn-py2-py-references:
**References**
Berry, M W, Minser, K S, 1999, `Algorithm 798: high-dimensional interpolation using the modified Shepard method`, ACM Trans. Math. Software (25), 353--366
Renka, R J, 1988, `Algorithm 661: QSHEP3D: Quadratic Shepard method for trivariate interpolation of scattered data`, ACM Trans. Math. Software (14), 151--152
"""
raise NotImplementedError
