dss_statistics

Returns statistics about various phases of the solving process.

Syntax

dss_statistics(handle, opt, statArr, retValues)

Fortran:

call dss_statistics(handle, opt, statArr, retValues)

Include Files

The FORTRAN 77 interface is specified in the mkl_dss.f77 include file, the Fortran 90 interface is specified in the mkl_dss.f90 include file, and the C interface is specified in the mkl_dss.h include file.

Description

The dss_statistics routine returns statistics about various phases of the solving process. This routine gathers the following statistics:

- time taken to do reordering,

- time taken to do factorization,

- duration of problem solving,

- determinant of the input matrix,

- inertia of the input matrix,

- number of floating point operations taken during factorization,

- total peak memory needed during the analysis and symbolic factorization,

- permanent memory needed from the analysis and symbolic factorization,

- memory consumption for the factorization and solve phases.

Statistics are returned in accordance with the input string specified by the parameter statArr. The value of the statistics is returned in double precision in a return array, which you must allocate beforehand.

For multiple statistics, multiple 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.

Statistics can only be requested at the appropriate stages of the solving process. For example, requesting FactorTime before a matrix is factored leads to errors.

The following table shows the point at which each individual statistics item can be requested:

Statistics Calling Sequences
Type of Statistics	When to Call
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 the matrix is real, symmetric, and indefinite.
Flops	After dss_factor_real or dss_factor_complex is completed successfully.
Peakmem	After dss_reorder is completed successfully.
Factormem	After dss_reorder is completed successfully.
Solvemem	After dss_factor_real or dss_factor_complex is completed successfully.

Input Parameters

Name	Type	Description
handle	FORTRAN 77: INTEGER8 Fortran 90:* TYPE (MKL_DSS_HANDLE), INTENT(IN) C: _MKL_DSS_HANDLE_t*	Pointer to the data structure storing intermediate DSS results (MKL_DSS_HANDLE).
opt	FORTRAN 77: INTEGER Fortran 90: INTEGER, INTENT(IN) C: _INTEGER_t const*	Parameter to pass the DSS options.
statArr	FORTRAN 77: INTEGER Fortran 90: INTEGER, INTENT(IN) C: char const*	Input string that defines the type of the returned statistics. The parameter can include one or more of the following string constants (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: the 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_base10^(det_pow)`. For complex matrices: the determinant is returned as det_pow, det_re, det_im in three consecutive return array locations, where `1.0 ≤abs(det_re) + abs(det_im) < 10.0` and `determinant = det_re, det_im10^(det_pow)`. Inertia Inertia of a real symmetric matrix is defined as a triplet of nonnegative integers `(p,n,z)`, where p is the number of positive eigenvalues, n is the number of negative eigenvalues, and z is the number of zero eigenvalues. Inertia is returned as three consecutive return array locations p, n, z. Computing inertia is recommended only for stable matrices. Unstable matrices can lead to incorrect results. Inertia of a k-by-k 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 the factorization. Peakmem Total peak memory in kilobytes that the solver needs during the analysis and symbolic factorization phase. Factormem Permanent memory in kilobytes that the solver needs from the analysis and symbolic factorization phase in the factorization and solve phases. Solvemem Total double precision memory consumption (kilobytes) of the solver for the factorization and solve phases.

Name

Type

Description

handle

FORTRAN 77: INTEGER*8

Fortran 90: TYPE (MKL_DSS_HANDLE), INTENT(IN)

C: _MKL_DSS_HANDLE_t*

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

opt

FORTRAN 77: INTEGER

Fortran 90: INTEGER, INTENT(IN)

C: _INTEGER_t const*

Parameter to pass the DSS options.

statArr

FORTRAN 77: INTEGER

Fortran 90: INTEGER, INTENT(IN)

C: char const*

Input string that defines the type of the returned statistics. The parameter can include one or more of the following string constants (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: the 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: the determinant is returned as det_pow, det_re, det_im in three consecutive return array locations, 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 as a triplet of nonnegative integers (p,n,z), where p is the number of positive eigenvalues, n is the number of negative eigenvalues, and z is the number of zero eigenvalues.

Inertia is returned as three consecutive return array locations p, n, z.

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

Inertia of a k-by-k 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 the factorization.

Peakmem

Total peak memory in kilobytes that the solver needs during the analysis and symbolic factorization phase.

Factormem

Permanent memory in kilobytes that the solver needs from the analysis and symbolic factorization phase in the factorization and solve phases.

Solvemem

Total double precision memory consumption (kilobytes) of the solver for the factorization and solve phases.

Note

To avoid problems in passing strings from Fortran to C, Fortran users must call the mkl_cvt_to_null_terminated_str routine before calling dss_statistics. Refer to the description of mkl_cvt_to_null_terminated_str for details.

Output Parameters

Name	Type	Description
retValues	FORTRAN 77: REAL8 Fortran 90:* REAL(KIND=8), INTENT(OUT) C: VOID const*	Value of the statistics returned.

Name

Type

Description

retValues

FORTRAN 77: REAL*8

Fortran 90: REAL(KIND=8), INTENT(OUT)

C: VOID const*

Value of the statistics returned.

Finding 'time used to reorder' and 'inertia' of a matrix

The example below illustrates the use of the dss_statistics routine.

To find the above values, call dss_statistics(handle, opt, statArr, retValue), where staArr is "ReorderTime,Inertia"

In this example, retValue has the following values:

retValue[0]: Time to reorder.
retValue[1]: Positive Eigenvalues.
retValue[2]: Negative Eigenvalues.
retValue[3]: Zero Eigenvalues.

Return Values

MKL_DSS_SUCCESS

MKL_DSS_INVALID_OPTION

MKL_DSS_STATISTICS_INVALID_MATRIX

MKL_DSS_STATISTICS_INVALID_STATE

MKL_DSS_STATISTICS_INVALID_STRING

MKL_DSS_MSG_LVL_ERR

MKL_DSS_TERM_LVL_ERR