Developer Reference

Contents

df?Interpolate1D/df?InterpolateEx1D

Runs data fitting computations.

Syntax

status
=
dfsInterpolate1D
(
task
,
type
,
method
,
nsite
,
site
,
sitehint
,
ndorder
,
dorder
,
datahint
,
r
,
rhint
,
cell
)
status
=
dfdInterpolate1D
(
task
,
type
,
method
,
nsite
,
site
,
sitehint
,
ndorder
,
dorder
,
datahint
,
r
,
rhint
,
cell
)
status
=
dfsInterpolateEx1D
(
task
,
type
,
method
,
nsite
,
site
,
sitehint
,
ndorder
,
dorder
,
datahint
,
r
,
rhint
,
cell
,
le_cb
,
le_params
,
re_cb
,
re_params
,
i_cb
,
i_params
,
search_cb
,
search_params
)
status
=
dfdInterpolateEx1D
(
task
,
type
,
method
,
nsite
,
site
,
sitehint
,
ndorder
,
dorder
,
datahint
,
r
,
rhint
,
cell
,
le_cb
,
le_params
,
re_cb
,
re_params
,
i_cb
,
i_params
,
search_cb
,
search_params
)
Include Files
  • mkl.h
Input Parameters
Name
Type
Description
task
DFTaskPtr
Descriptor of the task.
type
const MKL_INT
Type of spline-based computations. The parameter takes one or more values combined with an
OR
operation.
method
const MKL_INT
Computation method. The supported value is
DF_METHOD_PP
.
nsite
const MKL_INT
Number of interpolation sites.
site
const float*
for
dfsInterpolate1D
/
dfsInterpolateEx1D
const double*
for
dfdInterpolate1D
/
dfdInterpolateEx1D
Array of interpolation sites of size
nsite
. The structure of the array is defined by the
sitehint
parameter:
  • If sites form a non-uniform partition, the array should contain
    nsite
    values.
  • If sites form a uniform partition, the array should contain two entries that represent the left and the right interpolation sites. The first entry of the array contains the left-most interpolation point. The second entry of the array contains the right-most interpolation point.
sitehint
const MKL_INT
A flag describing the structure of the interpolation sites.
For the list of possible values of
sitehint
, see table
"Hint Values for Interpolation Sites"
.
If you set the flag to
DF_NO_HINT
, the library interprets the site-defined partition as non-uniform.
ndorder
const MKL_INT
Maximal derivative order increased by one to be computed at interpolation sites.
dorder
const MKL_INT*
Array of size
ndorder
that defines the order of the derivatives to be computed at the interpolation sites. If all the elements in
dorder
are zero, the library computes the spline values only. If you do not need interpolation computations, set
ndorder
to zero and pass a
NULL
pointer to
dorder
.
datahint
const float*
for
dfsInterpolate1D
/
dfsInterpolateEx1D
const double*
for
dfdInterpolate1D
/
dfdInterpolateEx1D
Array that contains additional information about the structure of partition
x
and interpolation sites. This data helps to speed up the computation. If you provide a
NULL
pointer, the routine uses the default settings for computations.
For details on the
datahint
array, see table
"Structure of the
datahint
Array"
.
r
float*
for
dfsInterpolate1D
/
dfsInterpolateEx1D
double*
for
dfdInterpolate1D
/
dfdInterpolateEx1D
Array for results. If you do not need spline-based interpolation, set this pointer to
NULL
.
rhint
const MKL_INT
A flag describing the structure of the results.
For the list of possible values of
rhint
, see table
"Hint Values for the
rhint
Parameter"
.
If you set the flag to
DF_NO_HINT
, the library stores the result in row-major format.
cell
MKL_INT*
Array of cell indices in partition
x
that contain the interpolation sites. Provide this parameter as input if
type
is
DF_INTERP_USER_CELL
. If you do not need cell indices, set this parameter to
NULL
.
le_cb
const
dfsInterpCallBack
for
dfsInterpolateEx1D
const
dfdInterpCallBack
for
dfdInterpolateEx1D
User-defined callback function for extrapolation at the sites to the left of the interpolation interval.
Set to
NULL
if you are not supplying a callback function.
le_params
const void*
Pointer to additional user-defined parameters passed by the library to the
le_cb
function.
Set to
NULL
if there are no additional parameters or if you are not supplying a callback function.
re_cb
const
dfsInterpCallBack
for
dfsInterpolateEx1D
const
dfdInterpCallBack
for
dfdInterpolateEx1D
User-defined callback function for extrapolation at the sites to the right of the interpolation interval.
Set to
NULL
if you are not supplying a callback function.
re_params
const void*
Pointer to additional user-defined parameters passed by the library to the
re_cb
function.
Set to
NULL
if there are no additional parameters or if you are not supplying a callback function.
i_cb
const
dfsInterpCallBack
for
dfsInterpolateEx1D
const
dfdInterpCallBack
for
dfdInterpolateEx1D
User-defined callback function for interpolation within the interpolation interval.
Set to
NULL
if you are not supplying a callback function.
i_params
const void*
Pointer to additional user-defined parameters passed by the library to the
i_cb
function.
Set to
NULL
if there are no additional parameters or if you are not supplying a callback function.
search_cb
const
dfsSearchCellsCallBack
for
dfsInterpolateEx1D
const
dfdSearchCellsCallBack
for
dfdInterpolateEx1D
User-defined callback function for computing indices of cells that can contain interpolation sites.
Set to
NULL
if you are not supplying a callback function.
search_params
const void*
Pointer to additional user-defined parameters passed by the library to the
search_cb
function.
Set to
NULL
if there are no additional parameters or if you are not supplying a callback function.
Output Parameters
Name
Type
Description
status
int
Status of the routine:
  • DF_STATUS_OK
    if the routine execution completed successfully.
  • Non-zero error code if the routine execution failed.
    See "Task Status and Error Reporting" for error code definitions.
r
Contains results of computations at the interpolation sites.
The
df?Interpolate1D
/
df?InterpolateEx1D
routines do not support in-place computations. You must provide non-aliasing memory locations for the
site
input parameter and the
r
output parameter.
cell
Array of cell indices in partition
x
that contain the interpolation sites, which is computed if
type
is
DF_CELL
.
Description
The
df?Interpolate1D
/
df?InterpolateEx1D
routine performs spline-based computations with user-defined settings. The routine supports two types of computations for interpolation sites provided in array
site
:
Computation Types Supported by the
df?Interpolate1D
/
df?InterpolateEx1D
Routines
Type
Description
DF_INTERP
Compute derivatives of predefined order. The derivative of the zero order is the spline value.
DF_INTERP_USER_CELL
Compute derivatives of predefined order given user-provided cell indices. The derivative of the zero order is the spline value.
For this type of the computations you should provide a valid
cell
array, which holds the indices of cells in the
site
array containing relevant interpolation sites.
DF_CELL
Compute indices of cells in partition
x
that contain the sites.
If the indices of cells which contain interpolation types are available before the call to
df?Interpolate1D
/
df?InterpolateEx1D
, you can improve performance by using the
DF_INTERP_USER_CELL
computation type.
If you pass any combination of
DF_INTERP
,
DF_INTERP_USER_CELL
, and
DF_CELL
computation types to the routine, the library uses the
DF_INTERP_USER_CELL
computation mode.
If you specify
DF_INTERP_USER_CELL
computation mode and a user-defined callback function for computing cell indices to
df?InterpolateEx1D
, the library uses the
DF_INTERP_USER_CELL
computation mode, and the call-back function is not called.
If the sites do not belong to interpolation interval [
a
,
b
] , the library uses:
  • polynomial
    P
    0
    of the spline constructed on interval [
    x
    0
    ,
    x
    1
    ] for computations at the sites to the left of
    a
    .
  • polynomial
    P
    n-2
    of the spline constructed on interval [
    x
    n-2
    ,
    x
    n-1
    ] for computations at the sites to the right of
    b
    .
Interpolation sites support the following hints:
Hint Values for Interpolation Sites
Value
Description
DF_NON_UNIFORM_PARTITION
Partition is non-uniform.
DF_UNIFORM_PARTITION
Partition is uniform.
DF_SORTED_DATA
Interpolation sites are sorted in the ascending order and define a non-uniform partition.
DF_NO_HINT
No hint is provided. By default, the partition defined by interpolation sites is interpreted as non-uniform.
If you pass a sorted array of interpolation sites to the
Intel® MKL
, set the
sitehint
parameter to the
DF_SORTED_DATA
value. The library uses this information when choosing the search algorithm and ignores any other data hints about the structure of the interpolation sites.
Data Fitting computation routines can use the following hints to speed up the computation:
  • DF_UNIFORM_PARTITION
    describes the structure of breakpoints and the interpolation sites.
  • DF_QUASI_UNIFORM_PARTITION
    describes the structure of breakpoints.
Pass the above hints to the library when appropriate.
For spline-based interpolation, you should set the derivatives whose values are required for the computation. You can provide the derivatives by setting the
dorder
array of size
ndorder
as follows:
Orders of derivatives
i
d
(
d
= 0, 1, ..,
nder
- 1)
, corresponding to non-zero derivatives to be calculated, form the array {
i
d
} of length
nder
ndorder
.
The storage format for the interpolation results is specified using the
rhint
parameter values. For each storage format, Table Hint Values for the
rhint
Parameter
describes how to get the result
R
(
j
,
s
,
i
d
) from array
r
, for function index
j
(0
j
yn
- 1)
, site number
s
(0
s
nsite
- 1)
, and derivative index
i
d
(0
d
nder
- 1)
, where
yn
is the number of functions,
nsite
is the number of sites, and
nder
is the total number of non-zero derivatives for interpolation. The array
r
can be either a one-dimensional array of size
ny
*
nder
*
nsite
or a three-dimensional array with the dimensions described in the table.
Hint Values for the
rhint
Parameter
Value
Location of
R
(
j
,
s
,
i
d
), One-dimensional Array Storage
Location of
R
(
j
,
s
,
i
d
), Three-dimensional Array Storage
DF_MATRIX_STORAGE_FUNCS_SITES_DERS
(
DF_MATRIX_STORAGE_ROWS
)
r
[
d
+
nder
*(
s
+
nsite
*
j
)]
r
[
j
][
s
][
d
]
r
declared as
r
[
ny
][
nsite
][
nder
]
.
DF_MATRIX_STORAGE_FUNCS_DERS_SITES
(
DF_MATRIX_STORAGE_COLS
)
r
[
s
+
nsite
*(
d
+
nder
*
j
)]
r
[
j
][
d
][
s
]
r
declared as
r
[
ny
][
nder
][
nsite
]
.
DF_MATRIX_STORAGE_SITES_FUNCS_DERS
r
[
d
+
nder
*(
j
+
ny
*
s
)]
r
[
s
][
j
][
d
]
r
declared as
r
[
nsite
][
ny
][
nder
]
.
DF_MATRIX_STORAGE_SITES_DERS_FUNCS
r
[
j
+
ny
*(
d
+
nder
*
s
)]
r
[
s
][
d
][
j
]
r
declared as
r
[
nsite
][
nder
][
ny
]
.
DF_NO_HINT
No hint is provided. By default, the results are stored as in
rhint
=
DF_MATRIX_STORAGE_FUNCS_SITES_DERS
.
The following figures show the structure of the storage formats. Each shows sequential memory layout line by line, left to right.
  • Storage in
    r
    for
    rhint
    =
    DF_MATRIX_STORAGE_FUNCS_SITES_DERS
    (
    DF_MATRIX_STORAGE_ROWS
    ):
  • Storage in
    r
    for
    rhint
    =
    DF_MATRIX_STORAGE_FUNCS_DERS_SITES
    (
    DF_MATRIX_STORAGE_COLS
    ):
  • Storage in
    r
    for
    rhint
    =
    DF_MATRIX_STORAGE_SITES_FUNCS_DERS
    :
  • Storage in
    r
    for
    rhint
    =
    DF_MATRIX_STORAGE_SITES_DERS_FUNCS
    :
To speed up Data Fitting computations, use the
datahint
parameter that provides additional information about the structure of the partition and interpolation sites. This data represents a floating-point or a double array with the following structure:
Structure of the
datahint
Array
Element Number
Description
0
Task dimension
1
Type of additional information
2
Reserved field
3
The total number
q
of elements containing additional information.
4
Element (1)
...
...
q
+3
Element (
q
)
Data Fitting computation functions support the following types of additional information for
datahint
[1]
:
Types of Additional Information
Type
Element Number
Parameter
DF_NO_APRIORI_INFO
0
No parameters are provided. Information about the data structure is absent.
DF_APRIORI_MOST_LIKELY_CELL
1
Index of the cell that is likely to contain interpolation sites.
To compute indices of the cells that contain interpolation sites, provide the pointer to the array of size
nsite
for the results. The library supports the following scheme of cell indexing for the given partition{
x
i
},
i
=1,...,
n
x
:
cell
[
j
]
=
i
, if
site
[
j
]
∈[
x
i
,
x
i
+1
),
i
= 0,...,
nx
- 2,
cell
[
j
]
=
nx
- 1, if
site
[
j
]
∈[
x
nx
- 1
,
x
nx
],
cell
[
j
]
=