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 sizenNonZeros.

dss_define_structure communicates to the solver the locations of thenNonZeronumber of non-zero elements in a matrix of sizenRowsbynCols. Currently, the CXML direct sparse solver only operate on square matrices, sonRowsmust be equal tonCols.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
rowIndexandcolumns. Refer to the "Using Direct Sparse Solvers" section of theCXML Reference Manualand theDirect Sparse Solvers Referencebooklet for a detailed description ofrowIndexandcolumnsindex.

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.

Ifoptcontains 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

optcontains 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 lengthnRows, wherenRowsis 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_complex

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 sizenNonZeros.

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 arrayrValuesorcValues. The arraysrValuesandcValuesare assumed to be of lengthnNonZerosas defined in a previous call to dss_define_structure.The

optargument 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 inrValuesandcValuesdescribe 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_complex

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

nRowsbynRhs.

2. Two dimensional array of sizenColsbynRhs.

For each right hand side column vector defined inxRhsValues(wherexis one ofrorc), these routines compute the corresponding solutions vector and place it in the arrayxSolValues.The lengths of the lengths of the right-hand side and solution vectors,

nColsandnRowsrespectively, 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 asdet_pow,det_basein 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 asdet_pow,det_re,det_imin 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) wherepis a number of positive eigenvalues,nis number of negative eigenvalues, andzis number of zero eigenvalues. Inertia will be returned as three consecutive return array locations asp,n,z.

Computing Inertia is only recommended for stable matrices. Unstable matrices can lead to incorrect results.

The Inertia of akxkreal 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 aboutFactorTimebefore a matrix is factored will lead to errors.The following table shows the point at which each statistic can be called.

ReorderTimeAfter dss_reorderis completed successfully.FactorTimeAfter dss_factor_realordss_factor_complexis completed successfullySolveTimeAfter dss_solve_realordss_solve_complexis completed successfully.DeterminantAfter dss_factor_realordss_factor_complexis completed successfully.InertiaAfter dss_factor_realis completed successfully and matrix is real, symmetric, and indefinite.FlopsAfter dss_factor_realordss_factor_complexis completed successfully.

Finding "time used to reorder" and "inertia" of a matrix.To find these values, call

dss_statistics(handle, opt, statArr, retValues), where:statArris "ReorderTime,Inertia".In this example,

retValueswill 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