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.
cxml_cvt_to_null_terminated_str (destStr,destLen,srcStr)
destStr
integer
One-dimensional array of integer.destLen
integer
Length of destStr.srcStr
string
Input string.
cxml_cvt_to_null_terminated_str is used to pass character strings from Fortran routines to C routines. The strings are converted into integer arrays before being passed to C. Using this routine avoids the problems that can occur on some platforms when passing strings from Fortran to C. The use of this routine is highly recommended.
dss_create (handle, opt)
handle : OUTPUT : CXML_DSS_HANDLE
opt : INPUT : INTEGER
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.
CXML_DSS_MSG_LVL_WARNING
CXML_DSS_TERM_LVL_ERROR
CXML_DSS_SUCCESS
CXML_DSS_INVALID_OPTION
CXML_DSS_OUT_OF_MEMORY
dss_delete (handle, opt)
handle : OUTPUT : CXML_DSS_HANDLE
opt : INPUT : INTEGER
dss_delete is called to delete all of the data structures created during the solutions process.
CXML_DSS_MSG_LVL_WARNING
CXML_DSS_TERM_LVL_ERROR
CXML_DSS_SUCCESS
CXML_DSS_INVALID_OPTION
CXML_DSS_OUT_OF_MEMORY
dss_define_structure (handle, opt, rowIndex, nRows, nCols, columns, nNonZeros)
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.
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:
- 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- 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.
CXML_DSS_SYMMETRIC
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 (handle, opt, perm)
handle : OUTPUT : CXML_DSS_HANDLE
opt : INPUT : INTEGER
perm : (See Description) : INTEGER (See 1)1. Array of length nRows.
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.
CXML_DSS_AUTO_ORDER
CXML_DSS_SUCCESS
CXML_DSS_STATE_ERR
CXML_DSS_INVALID_OPTION
CXML_DSS_OUT_OF_MEMORY
dss_factor_real (handle, opt, rValues)dss_factor_complex (handle, opt, cValues)
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.
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.
CXML_DSS_POSITIVE_DEFINITE
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 (handle, opt, rRhsValues, nRhs, rSolValues)dss_solve_complex (handle, opt, cRhsValues, nRhs, cSolValues)
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.
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.
None
CXML_DSS_SUCCESS
CXML_DSS_STATE_ERR
CXML_DSS_INVALID_OPTION
CXML_DSS_OUT_OF_MEMORY
dss_statistics (handle, opt, statArr, retValues)
handle : INPUT : CXML_DSS_HANDLE
opt : INPUT : INTEGER
statArr : INPUT : STRING
retValues : OUTPUT : DOUBLE PRECISION
The dss_statistics routine returns statistics about various phases of the solving process. dss_statistics can be used to gather statistics in the following areas: time taken to do reordering, time taken to do factorization, problem solving duration, determinant of a matrix, inertia of a matrix, and number of floating point operations taken during factorization.Statistics are returned corresponding to the specified input string. The value of the statistics is returned in double precision in a return array allocated by user. For multiple statistics, string constants separated by commas can be used as input. Return values are put into the return array in the same order as specified in the input string.
Note
To avoid problems in passing strings from Fortran to C, Fortran users must call the cxml_cvt_to_null_terminated_str routine before calling dss_statistics. Refer to the description of cxml_cvt_to_null_terminated_str for details.This routine expects an input string of one or more of the following string constants. Note that the case of the input string has no effect.
ReorderTime
Amount of time taken to do the reordering.FactorTime
Amount of time taken to do the factorization.SolveTime
Amount of time taken to solve the problem after factorization.Determinant
Determinant of the matrix A. For real matrices, determinant is returned as det_pow,det_base in two consecutive return array locations, where: 1.0 <= abs(det_base) < 10.0 and determinant = det_base*10**det_pow.
For complex matrices, determinant is returned as det_pow,det_re,det_im in three consecutive return array locations, where: where 1.0 <= abs(det_re) + abs(det_im) < 10.0 and determinant=(det_re,det_im)*10**det_pow.Inertia
Inertia of a real symmetric matrix is defined to be a triplet of non-negative integers (p,n,z) where p is a number of positive eigenvalues, n is number of negative eigenvalues, and z is number of zero eigenvalues. Inertia will be returned as three consecutive return array locations as p,n,z.
Computing Inertia is only recommended for stable matrices. Unstable matrices can lead to incorrect results.
The Inertia of a kxk real symmetric positive definite matrix is always (k,0,0). Therefore Inertia is returned only in cases of real symmetric indefinite matrices. For all other matrix types, an error message is returned.Flops
Number of floating point operations performed during factorization.
Statistics Calling Sequences
Statistics should only be requested at appropriate stages of the solving process. For example, inquiring about FactorTime before a matrix is factored will lead to errors.The following table shows the point at which each statistic can be called.
ReorderTime After dss_reorder is completed successfully. FactorTime After dss_factor_real or dss_factor_complex is completed successfully SolveTime After dss_solve_real or dss_solve_complex is completed successfully. Determinant After dss_factor_real or dss_factor_complex is completed successfully. Inertia After dss_factor_real is completed successfully and matrix is real, symmetric, and indefinite. Flops After dss_factor_real or dss_factor_complex is completed successfully.
Finding "time used to reorder" and "inertia" of a matrix.To find these values, call dss_statistics(handle, opt, statArr, retValues) , where: statArr is "ReorderTime,Inertia".
In this example, retValues will have the following values:
retValue[0] - Time to reorder retValue[1] - Positive Eigenvalues retValue[2] - Negative Eigenvalues retValue[3] - Zero Eigenvalues
None
CXML_DSS_SUCCESS success CXML_DSS_STATISTICS_ERR specified statistics option invalid CXML_DSS_STATISTICS_INVALID_STATE statistics invalid at this stage CXML_DSS_STATISTICS_INVALID_MATRIX invalid matrix type for specified statistics