Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

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

Document Table of Contents

pardiso_export

Places pointers dedicated for sparse representation of a requested matrix (values, rows, and columns) into MKL PARDISO

Syntax

void pardiso_export (const _MKL_DSS_HANDLE_t pt, void* values, MKL_INT* rows, MKL_INT* columns, MKL_INT* step, MKL_INT* iparm, MKL_INT* error);

Include Files

  • mkl.h

Description

This auxiliary routine places pointers dedicated for sparse representation of a requested matrix (values, rows, and columns) into MKL PARDISO. The matrix will be stored in the three-array variant of the compressed sparse row (CSR3 format) with 0-based indexing.

NOTE:

Currently, this routine can be used only for a sparse Schur complement matrix. All parameters related to the Schur complement matrix (perm, iparm) must be set before the reordering stage of MKL PARDISO (phase = 11) is called.

Input Parameters

pt

Array with a size of 64. Handle to internal data structure for the Intel® MKL PARDISO solver. The entries must be set to zero prior to the first call to pardiso. Unique for factorization.

iparm

This array is used to pass various parameters to Intel® MKL PARDISO and to return some useful information after execution of the solver.

step

Stage indicator. These are the currently supported values:

Step value Notes
1

Used to place pointers related to a Schur complement matrix in MKL PARDISO. The routine with step equal to 1 must be called between the reordering and factorization phases of MKL PARDISO.

−1

Used to clean the internal handle.

Input/Output Parameters

values

Parameter type: input/output parameter.

This array contains the non-zero elements of the requested matrix.

rows

Parameter type: input/output parameter.

Array of size (size + 1)

For CSR3 format, rows[i] ( i < size ) points to the first column index of row i in the array columns; that is, rows[i] gives the index of the element in the array values that contains the first non-zero element from row i of the sparse matrix. The last element, rows[size], is equal to the number of non-zero elements in the sparse matrix.

columns

Parameter type: input/output parameter.

This array contains the column indices for the non-zero elements of the requested matrix.

error

Parameter type: output parameter.

The error status:

  • 0 indicates no error.
  • 1 indicates inconsistent input data.

Usage Example

The following C-style example demonstrates how to use the pardiso_export routine to get the sparse representation (that is, three-array CSR format) of a Schur complement matrix.

#include "mkl.h"

/*
 * Call the reordering phase of MKL PARDISO with iparm[35] set to -1 in
 * order to compute the Schur complement matrix only, or -2 to compute all
 * factorization arrays.  perm array indices related to the Schur complement
 * matrix must be set to 1.
 */
phase = 11;
for ( i = 0; i < schur_size; i++ ) { perm[i] = 1.; }
iparm[35] = -1;
pardiso(pt, &maxfct, &mnum, &mtype, &phase, &n, a, ia, ja, perm, &nrhs,
  iparm, &msglvl, b, x, &error);

/*
 * After the reordering phase, iparm[35] will contain the number of non-zero
 * elements for the Schur complement matrix.  Arrays dedicated to the sparse
 * representation of the Schur complement matrix must be allocated before
 * the factorization stage of MKL PARDISO is called.
 */
schur_nnz     = iparm[35];
schur_rows    = (MKL_INT   *) mkl_malloc(schur_size+1, ALIGNMENT);
schur_columns = (MKL_INT   *) mkl_malloc(schur_nnz , ALIGNMENT);
schur_values  = (DATA_TYPE *) mkl_malloc(schur_nnz , ALIGNMENT);

/*
 * Call to the pardiso_export routine with step equal to 1 in order to put
 * pointers related to the three-array CSR format into MKL PARDISO:
 */
pardiso_export(pt, schur_values, schur_ia, schur_ja, &step, iparm, &error);

/*
 * Call the factorization phase of PARDISO with iparm[35] equal to -1 or -2
 * to compute the Schur complement matrix:
 */
phase = 22;
iparm[35] = -1;
pardiso(pt, &maxfct, &mnum, &mtype, &phase, &n, a, ia, ja, perm, &nrhs,
  iparm, &msglvl, b, x, &error);

/*
 * After the factorization stage, schur_values, schur_rows, and
 * schur_columns will contain the Schur complement matrix in CSR3 format.
 */