Direct Sparse Solvers

Direct Sparse Solver Routines

This section describes the user-callable CXML direct sparse solver subroutines.

For each routine, a description is provided along with information about the routine's format, arguments, default options, and errors.

Examples showing the use of these routines are provided in the "Using Direct Sparse Solvers" section of the CXML Reference Guide.

dss_create

Format

dss_create (handle, opt)

Arguments


handle : OUTPUT : CXML_DSS_HANDLE
opt : INPUT : INTEGER

Description

dss_create is called to initialize the solver. After the call to dss_create, all subsequent invocations of CXML direct sparse solver routines should use the value of handle returned by dss_create.

Warning: Do not write the value of handle directly.

Default Options


CXML_DSS_MSG_LVL_WARNING
CXML_DSS_TERM_LVL_ERROR

Return Values


CXML_DSS_SUCCESS
CXML_DSS_INVALID_OPTION
CXML_DSS_OUT_OF_MEMORY

dss_delete

Format

dss_delete (handle, opt)

Arguments


handle : OUTPUT : CXML_DSS_HANDLE
opt : INPUT : INTEGER

Description

dss_delete is called to delete all of the data structures created during the solutions process.

Default Options


CXML_DSS_MSG_LVL_WARNING
CXML_DSS_TERM_LVL_ERROR

Return Values


CXML_DSS_SUCCESS
CXML_DSS_INVALID_OPTION
CXML_DSS_OUT_OF_MEMORY

dss_define_structure

Format

dss_define_structure (handle, opt, rowIndex, nRows, nCols, columns, nNonZeros)

Arguments


handle : OUTPUT : CXML_DSS_HANDLE
opt : INPUT : INTEGER
rowIndex : INPUT : INTEGER (see 1)
nRows : INPUT : INTEGER
nCols : INPUT : INTEGER
columns : INPUT : INTEGER (see 2)
nNonZeros : INPUT : INTEGER

1. Array of size min(nRows, nCols)+1.
2. Array of size nNonZeros.

Description

dss_define_structure communicates to the solver the locations of the nNonZero number of non-zero elements in a matrix of size nRows by nCols. Currently, the CXML direct sparse solver only operate on square matrices, so nRows must be equal to nCols.

Communicating the locations of the non-zeros takes place in two steps:

  1. Define the general non-zero structure of the matrix by specifying one of the following option arguments:
    CXML_DSS_SYMMETRIC_STRUCTURE
    CXML_DSS_SYMMETRIC
    CXML_DSS_NON_SYMMETRIC
  2. Provide the actual locations of the non-zeros by means of the arrays rowIndex and columns. Refer to the "Using Direct Sparse Solvers" section of the CXML Reference Manual and the Direct Sparse Solvers Reference booklet for a detailed description of rowIndex and columns index.

Note: Currently, DSS does not directly support non-symmetric matrices. Instead, when the CXML_DSS_NON_SYMMETRIC option is specified, DSS will convert non-symmetric matrices into symmetrically structured matrices by adding zeros in the appropiate place.

Default Options


CXML_DSS_SYMMETRIC

Return Values


CXML_DSS_SUCCESS
CXML_DSS_STATE_ERR
CXML_DSS_INVALID_OPTION
CXML_DSS_COL_ERR
CXML_DSS_NOT_SQUARE
CXML_DSS_TOO_FEW_VALUES
CXML_DSS_TOO_MANY_VALUES

dss_reorder

Format

dss_reorder (handle, opt, perm)

Arguments


handle : OUTPUT : CXML_DSS_HANDLE
opt : INPUT : INTEGER
perm : (See Description) : INTEGER (See 1)

1. Array of length nRows.

Description

If opt contains the options CXML_DSS_AUTO_ORDER, then dss_reorder computes a permutation vector that minimizes the fill-in during the factorization phase. For this option, the perm array is never accessed.

If opt contains the option CXML_DSS_MY_ORDER, then the array perm is considered to be a permutation vector supplied by the user. In this case, the array perm is of length nRows, where nRows is the number of rows in the matrix as defined by the previous call to dss_define_structure.

Default Options


CXML_DSS_AUTO_ORDER

Return Values


CXML_DSS_SUCCESS
CXML_DSS_STATE_ERR
CXML_DSS_INVALID_OPTION
CXML_DSS_OUT_OF_MEMORY

dss_factor_real
dss_factor_complex

Format

dss_factor_real (handle, opt, rValues)

dss_factor_complex (handle, opt, cValues)

Arguments


handle : INPUT : CXML_DSS_HANDLE
opt : INPUT : INTEGER
rValues : INPUT : DOUBLE PRECISION (see 1)
cValues : INPUT : DOUBLE COMPLEX (see 2)

1. Array of size nNonZeros.
2. Array of size nNonZeros.

Description

These routines compute the factorization of the matrix whose non-zero locations were previously specified by a call to dss_define_structure and whose non-zero values are given in the array rValues or cValues. The arrays rValues and cValues are assumed to be of length nNonZeros as defined in a previous call to dss_define_structure.

The opt argument should contain one of the following options: CXML_DSS_POSITIVE_DEFINITE, CXML_DSS_INDEFINITE, CXML_DSS_HERMITIAN_POSITIVE_DEFINITE or CXML_DSS_HERMITIAN_INDEFINITE - depending on whether the non-zero values in rValues and cValues describe a positive definite, indefinite, or Hermitian matrix.

Default Options


CXML_DSS_POSITIVE_DEFINITE

Return Values


CXML_DSS_SUCCESS
CXML_DSS_STATE_ERR
CXML_DSS_INVALID_OPTION
CXML_DSS_OPTION_CONFLICT
CXML_DSS_OUT_OF_MEMORY
CXML_DSS_ZERO_PIVOT

dss_solve_real
dss_solve_complex

Format

dss_solve_real (handle, opt, rRhsValues, nRhs, rSolValues)

dss_solve_complex (handle, opt, cRhsValues, nRhs, cSolValues)

Arguments


handle : INPUT : CXML_DSS_HANDLE
opt : INPUT : INTEGER
Rhs : INPUT : INTEGER
rRhsValues : INPUT : DOUBLE PRECISION (see 1)
rSolValues : OUTPUT : DOUBLE PRECISION (see 2)
cRhsValues : INPUT : DOUBLE COMPLEX (see 1)
cSolValues : OUTPUT : DOUBLE COMPLEX (see 2)

1. Two dimensional array of size nRows by nRhs.
2. Two dimensional array of size nCols by nRhs.

Description

For each right hand side column vector defined in xRhsValues (where x is one of r or c), these routines compute the corresponding solutions vector and place it in the array xSolValues.

The lengths of the lengths of the right-hand side and solution vectors, nCols and nRows respectively, are assumed to have been defined in a previous call to dss_define_structure.

Default Options


None

Return Values


CXML_DSS_SUCCESS
CXML_DSS_STATE_ERR
CXML_DSS_INVALID_OPTION
CXML_DSS_OUT_OF_MEMORY


CXML Home Page

Index of CXML Routines