readhbpat.c File Reference

---

Detailed Description

Routine to read the pattern of a file stored in Harwell-Boeing format.

Adapted from the "dreadhb.c" routine written by Xiaoye Li <xiaoye@nersc.gov> for SuperLU v2.0.

-- SuperLU routine (version 2.0) -- Univ. of California Berkeley, Xerox Palo Alto Research Center, and Lawrence Berkeley National Lab. November 15, 1997

Updated: August 2, 2001 by rich vuduc <richie@cs.berkeley.edu>

• Added a "filename" parameter to dreadhb.

Updated: November 10, 2002 by rich vuduc <richie@cs.berkeley.edu>

• Patched dParseIntFormat and dParseFloatFormat to handle implicit-1s correctly (i.e., "(I7)" --> 1 int of size 7).

Updated: October 2004 by rich vuduc <richie@cs.berkeley.edu>

• Changed some routine names.
• Changed malloc calls to oski_Malloc calls.
• Changed the return types of routines that always return the same value to 'void'.
• Changed dReadVector so that it does *not* convert integers to 0-based indices.

Updated: November 2004 by rich vuduc <richie@cs.berkeley.edu>

• Changed main read routine to use size_t parameters instead of int parameters (for dParseIntFormat, for example).

#include <assert.h>
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <oski/common.h>
#include <oski/matrix.h>
#include <oski/matcreate.h>
#include "array_util.h"
#include "readhbpat.h"

Functions
static void	dDumpLine (FILE *fp)
	Eat up the rest of the current line.
static void	dParseIntFormat (const char *buf, size_t *num, size_t *size)
	Parse a Fortran-style integer format string.
static void	dReadVector (FILE *fp, size_t n, oski_index_t *where, size_t perline, size_t persize)
	Read a stream of formatted integers from an input file.
int	readhb_pattern (const char *filename, oski_index_t *p_m, oski_index_t *p_n, oski_index_t *p_nnz, oski_index_t **p_ptr, oski_index_t **p_ind, char *mattype)
	Read the raw pattern of a sparse matrix stored in Harwell-Boeing formatted file in compressed-sparse column format.
static int	is_csc_lower_tri (oski_index_t n, const oski_index_t *ptr, const oski_index_t *ind, oski_index_t base)
	Returns 1 <==> the given CSC matrix array pattern corresponds to that of a lower triangular matrix, and 0 otherwise.
static int	is_csc_upper_tri (oski_index_t n, const oski_index_t *ptr, const oski_index_t *ind, oski_index_t base)
	Returns 1 <==> the given CSC matrix array pattern corresponds to that of a upper triangular matrix, and 0 otherwise.
static void	ResetDiagImag (oski_index_t m, oski_index_t *ptr, oski_index_t *ind, oski_value_t *val, oski_index_t indbase)
	Sets the imaginary part of the diagonal elements to 0.
static void	reduce_offdiag_values (oski_index_t n, const oski_index_t *ptr, const oski_index_t *ind, oski_value_t *val, oski_index_t indbase)
	Reduce off-diagonal values by a factor of 2*n Main purpose of this routine is to make triangular matrices better-conditioned.
static oski_index_t	count_diag_elems (oski_index_t n, const oski_index_t *ptr, const oski_index_t *ind, oski_index_t indbase)
	Returns the number of diagonal elements.
oski_matrix_t	readhb_pattern_matrix (const char *matfile, oski_index_t *p_m, oski_index_t *p_n, char *p_mattype, int expand_symm)
	Read the pattern of a sparse matrix from a Harwell-Boeing formatted file, and return it as a tunable matrix handle.
oski_matrix_t	readhb_pattern_matrix_nnz (const char *matfile, oski_index_t *p_m, oski_index_t *p_n, oski_index_t *p_nnz_stored, oski_index_t *p_nnz_true, char *p_mattype, int expand_symm)
	Read the pattern of a sparse matrix from a Harwell-Boeing formatted file, and return it as a tunable matrix handle.

---

Function Documentation

static void dDumpLine (  FILE *  fp  )  [static]

Eat up the rest of the current line. Reads characters one by one from 'fp' beginning at the current file position until a new-line ('\n') or carriage-return ('\r') is encountered. Parameters: [in,out]  fp  File.

static void dParseIntFormat (  const char *  buf, size_t *  num, size_t *  size )  [static]

Parse a Fortran-style integer format string. This routine parses integer format strings given by the regular expression: .* \( [0-9]* [Ii] [0-9]+ e.g., "(5I7)" (5 integers, each of maximum width 7), "(I14junk" (1 integer, of maximum width 14). Parameters: [in]  buf  Buffer containing the format. [out]  num  Number of integers. [out]  size  String width of integer.

static void dReadVector (  FILE *  fp, size_t  n, oski_index_t *  where, size_t  perline, size_t  persize )  [static]

Read a stream of formatted integers from an input file. Parameters: [in,out]  fp  File. [in]  n  Total number of integers to read. [out]  where  Array in which to return the integers read. [in]  perline  Number of integers per line of the input file. [in]  persize  Exact distance (in characters) between consecutive integer starting locations in the file. Precondition: This routine assumes there are at most 99 characters between newlines within the input file, and that every line has the exact number 'perline' integers of string-width persize.

int readhb_pattern (  const char *  filename, oski_index_t *  p_m, oski_index_t *  p_n, oski_index_t *  p_nnz, oski_index_t **  p_ptr, oski_index_t **  p_ind, char *  mattype )

Read the raw pattern of a sparse matrix stored in Harwell-Boeing formatted file in compressed-sparse column format. Parameters: [in]  filename  Name of the Harwell-Boeing file. [out]  p_m  Number of rows in the matrix. [out]  p_n  Number of columns in the matrix. [out]  p_nnz  Number of logical (NOT stored) non-zeros. [out]  p_ptr  Stores the column pointers. [out]  p_ind  Stores the row indices. [out]  mattype  Pointer to a buffer of size 4, used to return the Harwell-Boeing matrix type (see Note below). Returns: 0 on success, or an error code with a call to the error handler. If an error occurs, then none of the output parameters are changed. Precondition: The file must be in [RP][RUSH]A format. Harwell-Boeing format: a line-by-line accounting of a matrix stored in Harwell-Boeing format. (A72,A8) Col. 1 - 72: Title (TITLE) Col. 73 - 80: Key (KEY) (5I14) Col. 1 - 14: Total number of lines excluding header (TOTCRD) Col. 15 - 28: Number of lines for pointers (PTRCRD) Col. 29 - 42: Number of lines for row (or variable) indices (INDCRD) Col. 43 - 56: Number of lines for numerical values (VALCRD) Col. 57 - 70: Number of lines for right-hand sides (RHSCRD). This includes starting guesses and solution vectors if present, or zero to indicate no right-hand side data are present. (A3, 11X, 4I14) Col. 1 - 3: Matrix type (see below) (MXTYPE) Col. 15 - 28: Number of rows (or variables) (NROW) Col. 29 - 42: Number of columns (or elements) (NCOL) Col. 43 - 56: Number of row (or variable) indices (NNZERO) (equal to number of entries for assembled matrices) Col. 57 - 70 Number of elemental matrix entries (NELTVL) (zero in the case of assembled matrices) (2A16, 2A20) Col. 1 - 16: Format for pointers (PTRFMT) Col. 17 - 32: Format for row (or variable) indices (INDFMT) Col. 33 - 52: Format for numerical values of coefficient matrix (VALFMT) Col. 53 - 72 Format for numerical values of right-hand sides (RHSFMT) (A3, 11X, 2I14) Only present if there are right-hand sides present Col. 1: Right-hand side type: F for full storage or M for same format as matrix Col. 2: G if a starting vector(s) (Guess) is supplied. (RHSTYP) Col. 3: X if an exact solution vector(s) is supplied. Col. 15 - 28: Number of right-hand sides (NRHS) Col. 29 - 42: Number of row indices (NRHSIX) (ignored in case of unassembled matrices) Note: The three character type field on line 3 describes the matrix type. The following table lists the permitted values for each of the three characters. As an example of the type field, 'RSA' denotes that the matrix is real, symmetric, and assembled. First character R Real matrix C Complex matrix P Pattern only (no numerical values supplied) Second character S Symmetric U Unsymmetric H Hermitian Z Skew symmetric R Rectangular Third character A Assembled E Elemental matrices (unassembled) The type is returned through the string 'mattype', using all uppercase letters.

oski_matrix_t readhb_pattern_matrix_nnz (  const char *  matfile, oski_index_t *  p_m, oski_index_t *  p_n, oski_index_t *  p_nnz_stored, oski_index_t *  p_nnz_true, char *  p_mattype, int  expand_symm )

Read the pattern of a sparse matrix from a Harwell-Boeing formatted file, and return it as a tunable matrix handle. The non-zero values are replaced by random numbers in the interval (0,1]. Parameters: [in]  matfile  File to read. [in,out]  p_m  Pointer to scalar integer in which to return the number of matrix rows. May set to NULL if this information is not desired. [in,out]  p_n  Pointer to scalar integer in which to return the number of matrix columns. May set to NULL if this information is not desired. [in,out]  p_nnz_stored  Pointer to scalar integer in which to return the number of stored non-zeros. [in,out]  p_nnz_true  Pointer to scalar integer in which to return the number of true non-zeros. [in,out]  p_mattype  String buffer of length >= 3 in which to store the matrix type. May set to NULL if this information is not desired. This routine does NOT NULL-terminate mattype on return. Returns: A tunable matrix handle. On error, aborts the program with exit code 1, leaving *p_m, *p_n, and p_mattype unchanged. Only the first 3 characters of p_mattype are changed, and p_mattype is NOT NULL-terminated by this routine.

static void ResetDiagImag (  oski_index_t  m, oski_index_t *  ptr, oski_index_t *  ind, oski_value_t *  val, oski_index_t  indbase )  [static]

Sets the imaginary part of the diagonal elements to 0. This routine is used primarily to ensure that the diagonal of a Hermitian matrix is pure real.

---