Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 11/07/2023
Public

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

Document Table of Contents

dss_solve_real, dss_solve_complex

Compute the corresponding solution vector and place it in the output array.

Syntax

MKL_INT dss_solve_real(_MKL_DSS_HANDLE_t *handle, MKL_INT const *opt, void const *rRhsValues, MKL_INT const *nRhs, void *rSolValues)

MKL_INT dss_solve_complex(_MKL_DSS_HANDLE_t *handle, MKL_INT const *opt, void const *cRhsValues, MKL_INT const *nRhs, void *cSolValues)

Include Files

  • mkl.h

Description

For each right-hand side column vector defined in the arrays rRhsValues, cRhsValues, or RhsValues, these routines compute the corresponding solution vector and place it in the arrays rSolValues, cSolValues, or SolValues respectively.

NOTE:

The data type (single or double precision) of all arrays must be in correspondence with precision specified by the parameter opt in the routine dss_create.

The lengths of the right-hand side and solution vectors, nRows and nCols respectively, must be defined in a previous call to dss_define_structure.

By default, both routines perform the full solution step (it corresponds to phase = 33in Intel® oneAPI Math Kernel Library (oneMKL) PARDISO). The parameteropt enables you to calculate the final solution step-by-step, calling forward and backward substitutions.

If it is set to MKL_DSS_FORWARD_SOLVE, the forward substitution (corresponding to phase = 331in Intel® oneAPI Math Kernel Library (oneMKL) PARDISO) is performed;

if it is set to MKL_DSS_DIAGONAL_SOLVE, the diagonal substitution (corresponding to phase = 332in Intel® oneAPI Math Kernel Library (oneMKL) PARDISO) is performed, if possible;

if it is set to MKL_DSS_BACKWARD_SOLVE, the backward substitution (corresponding to phase = 333in Intel® oneAPI Math Kernel Library (oneMKL) PARDISO) is performed.

For more details about using these substitutions for different types of matrices, see Separate Forward and Backward Substitutionin the Intel® oneAPI Math Kernel Library (oneMKL) PARDISO solver description.

This parameter also can control the number of refinement steps that is used on the solution stage: if it is set to MKL_DSS_REFINEMENT_OFF, the maximum number of refinement steps equal to zero, and if it is set to MKL_DSS_REFINEMENT_ON (default value), the maximum number of refinement steps is equal to 2.

MKL_DSS_CONJUGATE_SOLVE option added to the parameter opt enables solving a conjugate transposed system AHX = B based on the factorization of the matrix A. This option is equivalent to the parameter iparm[11]= 1in Intel® oneAPI Math Kernel Library (oneMKL) PARDISO.

MKL_DSS_TRANSPOSE_SOLVE option added to the parameter opt enables solving a transposed system ATX = B based on the factorization of the matrix A. This option is equivalent to the parameter iparm[11]= 2in Intel® oneAPI Math Kernel Library (oneMKL) PARDISO.

Input Parameters

handle

Pointer to the data structure storing internal DSS results (MKL_DSS_HANDLE).

opt

Parameter to pass the DSS options.

nRhs

Number of the right-hand sides in the system of linear equations.

rRhsValues

Array of size nRows * nRhs. Contains real right-hand side vectors. Real data, single or double precision as it is specified by the parameter opt in the routine dss_create.

cRhsValues

Array of size nRows * nRhs. Contains complex right-hand side vectors. Complex data, single or double precision as it is specified by the parameter opt in the routine dss_create.

RhsValues

Array of size nRows * nRhs. Contains right-hand side vectors. Real or complex data, single or double precision as it is specified by the parameter opt in the routine dss_create.

Output Parameters

rSolValues

Array of size nCols * nRhs. Contains real solution vectors. Real data, single or double precision as it is specified by the parameter opt in the routine dss_create.

cSolValues

Array of size nCols * nRhs. Contains complex solution vectors. Complex data, single or double precision as it is specified by the parameter opt in the routine dss_create.

Return Values

MKL_DSS_SUCCESS

MKL_DSS_STATE_ERR

MKL_DSS_INVALID_OPTION

MKL_DSS_OUT_OF_MEMORY

MKL_DSS_DIAG_ERR

MKL_DSS_FAILURE

MKL_DSS_MSG_LVL_ERR

MKL_DSS_TERM_LVL_ERR

MKL_DSS_OOC_MEM_ERR

MKL_DSS_OOC_OC_ERR

MKL_DSS_OOC_RW_ERR