Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 2021.1
  • 12/04/2020
  • Public Content
Contents

df?Integrate1D/df?IntegrateEx1D

Computes a spline-based integral.

Syntax

status
=
dfsIntegrate1D
(
task
,
method
,
nlim
,
llim
,
llimhint
,
rlim
,
rlimhint
,
ldatahint
,
rdatahint
,
r
,
rhint
)
status
=
dfdIntegrate1D
(
task
,
method
,
nlim
,
llim
,
llimhint
,
rlim
,
rlimhint
,
ldatahint
,
rdatahint
,
r
,
rhint
)
status
=
dfsIntegrateEx1D
(
task
,
method
,
nlim
,
llim
,
llimhint
,
rlim
,
rlimhint
,
ldatahint
,
rdatahint
,
r
,
rhint
,
le_cb
,
le_params
,
re_cb
,
re_params
,
i_cb
,
i_params
,
search_cb
,
search_params
)
status
=
dfdIntegrateEx1D
(
task
,
method
,
nlim
,
llim
,
llimhint
,
rlim
,
rlimhint
,
ldatahint
,
rdatahint
,
r
,
rhint
,
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.
method
const MKL_INT
Integration method. The supported value is
DF_METHOD_PP
.
nlim
const MKL_INT
Number of pairs of integration limits.
llim
const float*
 for
dfsIntegrate1D
/
dfsIntegrateEx1D
const double*
 for
dfdIntegrate1D
/
dfdIntegrateEx1D
Array of size
nlim
 that defines the left-side integration limits.
llimhint
const MKL_INT
A flag describing the structure of the left-side integration limits
llim
.
For the list of possible values of
llimhint
, see table
"Hint Values for Integration Limits"
.
If you set the flag to the
DF_NO_HINT
 value, the library assumes that the left-side integration limits define a non-uniform partition.
rlim
const float*
 for
dfsIntegrate1D
/
dfsIntegrateEx1D
const double*
 for
dfdIntegrate1D
/
dfdIntegrateEx1D
Array of size
nlim
 that defines the right-side integration limits.
rlimhint
const MKL_INT
A flag describing the structure of the right-side integration limits
rlim
.
For the list of possible values of
rlimhint
, see table
"Hint Values for Integration Limits"
.
If you set the flag to the
DF_NO_HINT
 value, the library assumes that the right-side integration limits define a non-uniform partition.
ldatahint
const float*
 for
dfsIntegrate1D
/
dfsIntegrateEx1D
const double*
 for
dfdIntegrate1D
/
dfdIntegrateEx1D
Array that contains additional information about the structure of partition
x
 and left-side integration limits.
For details on the
ldatahint
 array, see table
"Structure of the
datahint
 Array"
 in the description of the
df?Interpolate1D
 function.
rdatahint
const float*
 for
dfsIntegrate1D
/
dfsIntegrateEx1D
const double*
 for
dfdIntegrate1D
/
dfdIntegrateEx1D
Array that contains additional information about the structure of partition
x
 and right-side integration limits.
For details on the
rdatahint
 array, see table
"Structure of the
datahint
 Array"
 in the description of the
df?Interpolate1D
 function.
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 Integration Results"
.
If you set the flag to the
DF_NO_HINT
 value, the library stores the results in row-major format.
le_cb
const
dfsIntegrCallBack
 for
dfsIntegrateEx1D
const
dfdIntegrCallBack
 for
dfdIntegrateEx1D
User-defined callback function for integration on interval
[
llim
[
i
]
,
min
(
rlim
[
i
]
,
a
))
 for
llim
[
i
]
 <
a
 .
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
dfsIntegrateEx1D
const
dfdInterpCallBack
 for
dfdIntegrateEx1D
User-defined callback function for integration on interval
[
max
(
llim
[
i
]
,
b
),
rlim
[
i
]
)
 for
rlim
[
i
]
≥
b
.
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
dfsIntegrCallBack
 for
dfsIntegrateEx1D
const
dfdIntegrCallBack
 for
dfdIntegrateEx1D
User-defined callback function for integration on interval [
max
(
a
,
llim
[
i
]
, ),
min
(
rlim
[
i
]
,
b
)).
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
dfsIntegrateEx1D
const
dfdSearchCellsCallBack
 for
dfdIntegrateEx1D
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
float*
 for
dfsIntegrate1D
/
dfsIntegrateEx1D
double*
 for
dfdIntegrate1D
/
dfdIntegrateEx1D
Array of
integration
 results. The size of the array should be sufficient to hold
nlim
*
ny
 values, where
ny
 is the dimension of the vector-valued function. The integration results are packed according to the settings in
rhint
.
The
df?Integrate1D
/
df?IntegrateEx1D
 routines do not support in-place computations. You must provide non-aliasing memory locations for the
llim
 and
rlim
 input parameters and the
r
 output parameter.
Description
The
df?Integrate1D
/
df?IntegrateEx1D
 routine computes spline-based integral on user-defined intervals
,
where
rl
i
 =
rlim
[
i
]
,
ll
i
 =
llim
[
i
]
, and
i
=
0, ...,
ny
 - 1
.
If
rlim
[
i
]
 <
llim
[
i
]
, the routine returns
The routine supports the following hint values for integration results:
Hint Values for Integration Results
Value
Description
DF_MATRIX_STORAGE_ROWS
Data is stored in row-major format according to C conventions.
DF_MATRIX_STORAGE_COLS
Data is stored in column-major format according to Fortran conventions.
DF_NO_HINT
No hint is provided. By default, the coordinates of vector-valued function
y
 are provided and stored in row-major format.
A common structure of the storage formats for the integration results is as follows:
  • Row-major format
    I
    (
    0
    ,
    0
    )
    ...
    I
    (
    0
    ,
    nlim
    - 1
    )
    ...
    ...
    ...
    I
     (
    ny
    - 1
    ,
    0
    )
    ...
    I
    (
    ny
    - 1
    ,
    nlim
    - 1
    )
  • Column-major format
    I
    (
    0
    ,
    0
    )
    ...
    I
     (
    ny
    - 1
    ,
    0
    )
    ...
    ...
    ...
    I
    (
    0
    ,
    nlim
    - 1
    )
    ...
    I
    (
    ny
    - 1
    ,
    nlim
    - 1
    )
Using the
llimhint
 and
rlimhint
 parameters, you can provide the following hint values for integration limits:
Hint Values for Integration Limits
Value
Description
DF_SORTED_DATA
Integration limits are sorted in the ascending order and define a non-uniform partition.
DF_NON_UNIFORM_PARTITION
Partition defined by integration limits is non-uniform.
DF_UNIFORM_PARTITION
Partition defined by integration limits is uniform.
DF_NO_HINT
No hint is provided. By default, partition defined by integration limits is interpreted as non-uniform.
To compute integration with splines unsupported in the Data Fitting component, use the extended version of the routine
df?IntegrateEx1D
. With this routine, you can provide user-defined callback functions that compute:
  • integrals within, to the left of, or to the right of the interpolation interval [
    a
    ,
    b
    ]
  • indices of cells that contain the provided integration limits or can serve as an approximation for computing the exact indices of such cells
If you do not pass callback functions, the routine uses the default settings.