Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/31/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

df?NewTask1D

Creates and initializes a new task descriptor for a one-dimensional Data Fitting task.

Syntax

status = dfsNewTask1D(&task, nx, x, xhint, ny, y, yhint)

status = dfdNewTask1D(&task, nx, x, xhint, ny, y, yhint)

Include Files
  • mkl.h
Input Parameters

Name

Type

Description

nx

const MKL_INT

Number of breakpoints representing partition of interpolation interval [a, b].

x

const float* for dfsNewTask1D

const double* for dfdNewTask1D

One-dimensional array containing the strictly sorted breakpoints from interpolation interval [a, b]. The structure of the array is defined by parameter xhint:

  • If partition is non-uniform or quasi-uniform, the array should contain nx strictly ordered values.
  • If partition is uniform, the array should contain two entries that represent endpoints of interpolation interval [a, b].

CAUTION:

The array must be strictly sorted. If it is unordered, the results of data fitting routines are not correct.

xhint

const MKL_INT

A flag describing the structure of partition x. For the list of possible values of xhint, see table "Hint Values for Partition x". If you set the flag to the DF_NO_HINT value, the library interprets the partition as non-uniform.

ny

const MKL_INT

Dimension of vector-valued function y.

y

const float* for dfsNewTask

const double* for dfdNewTask

Vector-valued function y, array of size nx*ny.

The storage format of function values in the array is defined by the value of flag yhint.

yhint

const MKL_INT

A flag describing the structure of array y. Valid hint values are listed in table "Hint Values for Vector-Valued Function y". If you set the flag to the DF_NO_HINT value, the library assumes that all ny coordinates of the vector-valued function y are provided and stored in row-major format.

Output Parameters

Name

Type

Description

task

DFTaskPtr

Descriptor of the task.

status

int

Status of the routine:

  • DF_STATUS_OK if the task is created successfully.
  • Non-zero error code if the task creation failed. See "Task Status and Error Reporting" for error code definitions.

Description

The df?NewTask1D routine creates and initializes a new Data Fitting task descriptor with user-specified parameters for a one-dimensional Data Fitting task. The x and nx parameters representing the partition of interpolation interval [a, b] are mandatory. If you provide invalid values for these parameters, such as a NULL pointer x or the number of breakpoints smaller than two, the routine does not create the Data Fitting task and returns an error code.

If you provide a vector-valued function y, make sure that the function dimension ny and the array of function values y are both valid. If any of these parameters are invalid, the routine does not create the Data Fitting task and returns an error code.

If you store coordinates of the vector-valued function y in non-contiguous memory locations, you can set the yhint flag to DF_1ST_COORDINATE, and pass only the first coordinate of the function into the task creation routine. After successful creation of the Data Fitting task, you can pass the remaining coordinates using the df?EditIdxPtr task editor.

If the routine fails to create the task descriptor, it returns a NULL task pointer.

The routine supports the following hint values for partition x:

Hint Values for Partition x

Value

Description

DF_NON_UNIFORM_PARTITION

Partition is non-uniform.

DF_QUASI_UNIFORM_PARTITION

Partition is quasi-uniform.

DF_UNIFORM_PARTITION

Partition is uniform.

DF_NO_HINT

No hint is provided. By default, partition is interpreted as non-uniform.

The routine supports the following hint values for the vector-valued function:

Hint Values for Vector-Valued Function y

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_1ST_COORDINATE

The first coordinate of vector-valued data is provided.

DF_NO_HINT

No hint is provided. By default, the coordinates of vector-valued function y are provided and stored in row-major format.

NOTE:

You must preserve the arrays x (breakpoints) and y (vector-valued functions) through the entire workflow of the Data Fitting computations for a task, as the task stores the addresses of the arrays for spline-based computations.