Adams Basic Package > Adams Solver > Welcome to Adams Solver Subroutines > Utility Subroutines > GET_SPARSE_MATRIX_DATA

GET_SPARSE_MATRIX_DATA

Returns the values entered in a dataset MATRIX statement (C++ or FORTRAN) in sparse matrix form given the statement identifier.

Use

Called By

Any user-written subroutine

Prerequisite

MATRIX statement in the dataset

Calling Sequence

 GET_SPARSE_MATRIX_DATA(id, rows, cols, vals, size, ierr)

Input Arguments

 
id
An integer variable that specifies the ID of the corresponding MATRIX statement.
size
An integer variable that specifies the size of the MATRIX. GET_SPARSE_MATRIX_DATA uses this value to compare against the MATRIX’s true size; a check for a valid call.

Output Arguments

 
rows
An integer array of size size that contains the row indices corresponding to the MATRIX values stored in vals.
cols
An integer array of size size that contains the column indices corresponding to the MATRIX values stored in vals.
vals
A double-precision array of size size that contains the values from the MATRIX statement in sparse form.
ierr
An integer variable that indicates the success of the call to GET_SPARSE_MATRIX_DATA:
■ierr=0
Successful
■ierr=1
Failed, no MATRIX having an identifier of ID exists in the dataset
■ierr=2
Failed, the value of size’ does not match the size of the MATRIX

Extended Definition

GET_SPARSE_MATRIX_DATA returns the values entered in a dataset MATRIX statement in sparse matrix form. It can be used with any matrix type, but may be inefficient for a large MATRIX of type full.
Sparse matrix form is a compact way of storing matrix data when many data entries are zero; only the non-zero values are stored. The rows and cols arrays provides the row and column matrix locations for the corresponding data in the vals array. When using GET_SPARSE_MATRIX_DATA to get data of a matrix type full, all values are returned. GET_SPARSE_MATRIX_DATA makes no attempt to reduce the size of the data by eliminating zero entries.
 
Tip:  
Call GET_MATRIX_INFO to get the size and type of the MATRIX.