Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 2021.1
  • 12/04/2020
  • Public Content
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® oneAPI Math Kernel Library
, 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
]
.