Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

Contents

df?EditPPSpline1D

Modifies parameters representing a spline in a Data Fitting task descriptor.

Syntax

status
=
dfsEditPPSpline1D
(
task
,
s_order
,
s_type
,
bc_type
,
bc
,
ic_type
,
ic
,
scoeff
,
scoeffhint
)
status
=
dfdEditPPSpline1D
(
task
,
s_order
,
s_type
,
bc_type
,
bc
,
ic_type
,
ic
,
scoeff
,
scoeffhint
)
Include Files
  • mkl.h
Input Parameters
Name
Type
Description
task
DFTaskPtr
Descriptor of the task.
s_order
const MKL_INT
Spline order.
The parameter takes one of the values described in table
"Spline Orders Supported by Data Fitting Functions"
.
s_type
const MKL_INT
Spline type.
The parameter takes one of the values described in table
"Spline Types Supported by Data Fitting Functions"
.
bc_type
const MKL_INT
Type of boundary conditions.
The parameter takes one of the values described in table
"Boundary Conditions Supported by Data Fitting Functions"
.
bc
const float*
 for
dfsEditPPSpline1D
const double*
 for
dfdEditPPSpline1D
Pointer to boundary conditions. The size of the array is defined by the value of parameter
bc_type
:
  • If you set free-end or not-a-knot boundary conditions, pass the
    NULL
     pointer to this parameter.
  • If you combine boundary conditions at the endpoints of the interpolation interval, pass an array of two elements.
  • If you set a boundary condition for the default quadratic spline or a periodic condition for Hermite or the default cubic spline, pass an array of one element.
ic_type
const MKL_INT
Type of internal conditions.
The parameter takes one of the values described in table
"Internal Conditions Supported by Data Fitting Functions"
.
ic
const float*
 for
dfsEditPPSpline1D
const double*
 for
dfdEditPPSpline1D
A non-
NULL
 pointer to the array of internal conditions. The size of the array is defined by the value of parameter
ic_type
:
  • If you set
    first derivatives
     or
    second derivatives
     internal conditions (
    ic_type
    =
    DF_IC_1ST_DER
     or
    ic_type
    =
    DF_IC_2ND_DER
    ), pass an array of
    n
    -1 derivative values at the internal points of the interpolation interval.
  • If you set the
    knot values
     internal condition for Subbotin spline (
    ic_type
    =
    DF_IC_Q_KNOT
    ) and the knot partition is non-uniform, pass an array of
    n
    +1 elements.
  • If you set the
    knot values
     internal condition for Subbotin spline (
    ic_type
    =
    DF_IC_Q_KNOT
    ) and the knot partition is uniform, pass an array of four elements.
scoeff
const float*
 for
dfsEditPPSpline1D
const double*
 for
dfdEditPPSpline1D
Spline coefficients. An array of size
ny
*
s_order
*(
nx
-1)
. The storage format of the coefficients in the array is defined by the value of flag
scoeffhint
.
scoeffhint
const MKL_INT
A flag describing the structure of the array of spline coefficients.
For valid hint values, see table
"Hint Values for Spline Coefficients"
.
The library stores the coefficients in row-major format. The default value is
DF_NO_HINT
.
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.
Description
The editor modifies parameters that describe the order, type, boundary conditions, internal conditions, and coefficients of a spline. The spline order definition is provided in the
"Mathematical Conventions"
 section. You can set the spline order to any value supported by Data Fitting functions. The table below lists the available values:
Spline Orders Supported by the Data Fitting Functions
Order
Description
DF_PP_STD
Artificial value. Use this value for look-up and step-wise constant interpolants only.
DF_PP_LINEAR
Piecewise polynomial spline of the second order (linear spline).
DF_PP_QUADRATIC
Piecewise polynomial spline of the third order (quadratic spline).
DF_PP_CUBIC
Piecewise polynomial spline of the fourth order (cubic spline).
To perform computations with a spline not supported by Data Fitting routines, set the parameter defining the spline order and pass the spline coefficients to the library in the supported format. For format description, see figure
"Row-major Coefficient Storage Format"
.
The table below lists the supported spline types:
Spline Types Supported by Data Fitting Functions
Type
Description
DF_PP_DEFAULT
The default spline type. You can use this type with linear, quadratic, or user-defined splines.
DF_PP_SUBBOTIN
Quadratic splines based on Subbotin algorithm, [
StechSub76
].
DF_PP_NATURAL
Natural cubic spline.
DF_PP_HERMITE
Hermite cubic spline.
DF_PP_BESSEL
Bessel cubic spline.
DF_PP_AKIMA
Akima cubic spline.
DF_LOOKUP_INTERPOLANT
Look-up interpolant.
DF_CR_STEPWISE_CONST_INTERPOLANT
Continuous right step-wise constant interpolant.
DF_CL_STEPWISE_CONST_INTERPOLANT
Continuous left step-wise constant interpolant.
If you perform computations with look-up or step-wise constant interpolants, set the spline order to the
DF_PP_STD
 value.
Construction of specific splines may require boundary or internal conditions. To compute coefficients of such splines, you should pass boundary or internal conditions to the library by specifying the type of the conditions and providing the necessary values. For splines that do not require additional conditions, such as linear splines, set condition types to
DF_NO_BC
 and
DF_NO_IC
, and pass
NULL
 pointers to the conditions. The table below defines the supported boundary conditions:
Boundary Conditions Supported by Data Fitting Functions
Boundary Condition
Description
Spline
DF_NO_BC
No boundary conditions provided.
All
DF_BC_NOT_A_KNOT
Not-a-knot boundary conditions.
Akima, Bessel, Hermite, natural cubic
DF_BC_FREE_END
Free-end boundary conditions.
Akima, Bessel, Hermite, natural cubic, quadratic Subbotin
DF_BC_1ST_LEFT_DER
The first derivative at the left endpoint.
Akima, Bessel, Hermite, natural cubic, quadratic Subbotin
DF_BC_1ST_RIGHT_DER
The first derivative at the right endpoint.
Akima, Bessel, Hermite, natural cubic, quadratic Subbotin
DF_BC_2ST_LEFT_DER
The second derivative at the left endpoint.
Akima, Bessel, Hermite, natural cubic, quadratic Subbotin
DF_BC_2ND_RIGHT_DER
The second derivative at the right endpoint.
Akima, Bessel, Hermite, natural cubic, quadratic Subbotin
DF_BC_PERIODIC
Periodic boundary conditions.
Linear, all cubic splines
DF_BC_Q_VAL
Function value at point
(
x
0
 +
x
1
)/2
Default quadratic
To construct a natural cubic spline, pass these settings to the editor:
  • DF_PP_CUBIC
     as the spline order,
  • DF_PP_NATURAL
     as the spline type, and
  • DF_BC_FREE_END
     as the boundary condition.
To construct a cubic spline with other boundary conditions, pass these settings to the editor:
  • DF_PP_CUBIC
     as the spline order,
  • DF_PP_NATURAL
     as the spline type, and
  • the required type of boundary condition.
For Akima, Hermite, Bessel, and default cubic splines use the corresponding type defined in Table Spline Types Supported by Data Fitting Functions.
You can combine the values of boundary conditions with a bitwise
OR
 operation. This permits you to pass combinations of first and second derivatives at the endpoints of the interpolation interval into the library. To pass a first derivative at the left endpoint and a second derivative at the right endpoint, set the boundary conditions to
DF_BC_1ST_LEFT_DER
 OR
DF_BC_2ND_RIGHT_DER
.
You should pass the combined boundary conditions as an array of two elements. The first entry of the array contains the value of the boundary condition for the left endpoint of the interpolation interval, and the second entry - for the right endpoint. Pass other boundary conditions as arrays of one element.
For the conditions defined as a combination of valid values, the library applies the following rules to identify the boundary condition type:
  • If not required for spline construction, the value of boundary conditions is ignored.
  • Not-a-knot condition has the highest priority. If set, other boundary conditions are ignored.
  • Free-end condition has the second priority after the not-a-knot condition. If set, other boundary conditions are ignored.
  • Periodic boundary condition has the next priority after the free-end condition.
  • The first derivative has higher priority than the second derivative at the right and left endpoints.
If you set the periodic boundary condition, make sure that function values at the endpoints of the interpolation interval are identical. Otherwise, the library returns an error code. The table below specifies the values to be provided for each type of spline if the periodic boundary condition is set.
Boundary Requirements for Periodic Conditions
Spline Type
Periodic Boundary Condition Support
Boundary Value
Linear
Yes
Not required
Default quadratic
No
Subbotin quadratic
No
Natural cubic
Yes
Not required
Bessel
Yes
Not required
Akima
Yes
Not required
Hermite cubic
Yes
First derivative
Default cubic
Yes
Second derivative
Internal conditions supported in the Data Fitting domain that you can use for the
ic_type
 parameter are the following:
Internal Conditions Supported by Data Fitting Functions
Internal Condition
Description
Spline
DF_NO_IC
No internal conditions provided.
DF_IC_1ST_DER
Array of first derivatives of size
n
-2, where
n
 is the number of breakpoints. Derivatives are applicable to each coordinate of the vector-valued function.
Hermite cubic
DF_IC_2ND_DER
Array of second derivatives of size
n
-2, where
n
 is the number of breakpoints. Derivatives are applicable to each coordinate of the vector-valued function.
Default cubic
DF_IC_Q_KNOT
Knot array of size
n
+1, where
n
 is the number of breakpoints.
Subbotin quadratic
To construct a Subbotin quadratic spline, you have three options to get the array of knots in the library:
  • If you do not provide the knots, the library uses the default values of knots
    t
     = {
    t
    i
    },
    i
     = 0, ...,
    n
     according to the rule:
    t
    0
     =
    x
    0
    ,
    t
    n
     =
    x
    n
    -1
    ,
    t
    i
     = (
    x
    i
     +
    x
    i
    -1
    )/2,
    i
     = 1, ...,
    n
     - 1
    .
  • If you provide the knots in an array of size
    n
     + 1, the knots form a non-uniform partition. Make sure that the knot values you provide meet the following conditions:
    t
    0
     =
    x
    0
    ,
    t
    n
     =
    x
    n
    -1
    ,
    t
    i
     ∈ (
    x
    i
    -1
    ,
    x
    i
    ),
    i
     = 1,...,
    n
     - 1.
  • If you provide the knots in an array of size 4, the knots form a uniform partition
    t
    0
     =
    x
    0
    ,
    t
    1
     =
    l
    ,
    t
    2
     =
    r
    ,
    t
    3
     =
    x
    n
     - 1
    , where
    l