HB Files
Harwell Boeing
Sparse Matrix File Format

HB, or the Harwell Boeing Sparse Matrix File Format, is used to store a sparse matrix in a file. The space required to represent the matrix is reduced by using a compressed column storage format. If the matrix is read from the file into memory, it is common to use the same compressed column storage to represent the matrix in memory.

A matrix is an m by n rectangular array of numbers. A sparse matrix is one in which "most" of the entries are zero. If the matrix is sparse enough, then it is often much more efficient not to allocate space for the full m*n set of entries, but rather to keep track of the location and value of the nonzero entries.

HB File Characteristics:

• ASCII;
• Organized by a cumbersome fixed format, rather than whitespace delimited;
• Oriented to FORTRAN, in the explicit use of FORTRAN FORMAT codes;

HB files begin with a header of 4, or sometimes 5, lines:

Line 1:

• TITLE, (72 characters)
• KEY, (8 characters)

Line 2:

• TOTCRD, integer, total number of data lines, (14 characters)
• PTRCRD, integer, number of data lines for pointers, (14 characters)
• INDCRD, integer, number of data lines for row or variable indices, (14 characters)
• VALCRD, integer, number of data lines for numerical values of matrix entries, (14 characters)
• RHSCRD, integer, number of data lines for right hand side vectors, starting guesses, and solutions, (14 characters)

Line 3:

• MXTYPE, matrix type (see table), (3 characters)
• blank space, (11 characters)
• NROW, integer, number of rows or variables, (14 characters)
• NCOL, integer, number of columns or elements, (14 characters)
• NNZERO, integer, number of row or variable indices. For "assembled" matrices, this is just the number of nonzero entries. (14 characters)
• NELTVL, integer, number of elemental matrix entries. For "assembled" matrices, this is 0. (14 characters)

Line 4:

• PTRFMT, FORTRAN I/O format for pointers, (16 characters)
• INDFMT, FORTRAN I/O format for row or variable indices, (16 characters)
• VALFMT, FORTRAN I/O format for matrix entries, (20 characters)
• RHSFMT, FORTRAN I/O format for right hand sides, initial guesses, and solutions, (20 characters)

Line 5: (only present if 0 < RHSCRD!)

• RHSTYP, describes the right hand side information, (3 characters)
• blank space, (11 characters)
• NRHS, integer, the number of right hand sides, (14 characters)
• NRHSIX, integer, number of row indices, (14 characters)

Each character of the MXTYPE variable specifies a separate fact about the matrix:

1. R, C or P indicates that the matrix values are real, complex, or that only the pattern of nonzeroes is going to be supplied. Note that if complex arithmetic is specified, then any data vectors included in the file will also be assumed to be complex. FORTRAN I/O treats a complex number as a simple pair of real numbers. Thus, a line that records the single complex number 12+17i would look like

               12.0  17.0
             

2. U, S, H, Z or R indicates that the matrix is symmetric, unsymmetric, Hermitian, skew symmetric, or rectangular. Each of these facts implies something about how the nonzero elements of the matrix are stored in the file.
   • If the matrix is unsymmetric (and square), then every nonzero element of the matrix corresponds to an entry in the file.
   • If the matrix is symmetric (which implies that it is square), (and which typically only occurs for real arithmetic), then half of the nonzero off-diagonal elements don't need to be stored in the file. A user need only specify the diagonal elements, and perhaps just those beneath the diagonal. A program reading the file must, correspondingly, assume that a value associated with one off-diagonal element should also be assigned to its corresponding transposed location.
   • If the matrix is Hermitian, (which implies that it is square) (and which typically only occurs for complex arithmetic), then half of the nonzero off-diagonal elements don't need to be stored in the file. A user need only specify the diagonal elements, and perhaps just those beneath the diagonal. A program reading the file must, correspondingly, assume that a value associated with one off-diagonal element should also be used to assign a value to its corresponding transposed location.
   • If the matrix is skew symmetric, (which implies that it is square) (and which typically only occurs for real arithmetic), then the diagonal is zero, and only half of the nonzero offdiagonal elements need to be stored. (I believe that the Z code is only appropriate for a real matrix, and that the case of a skew Hermitian matrix is not provide for!)
   • If the matrix is rectangular, then every nonzero element of the matrix must be stored. In effect, this is the same as the unsymmetric case.
3. A indicates that the matrix is "assembled" (the typical case) while E indicates that the matrix is a finite element matrix that is going to be described as the "sum" of a set of smaller matrices.

Each character of the RHSTYP specifies a separate fact about the right hand side information. (Of course, if there are no right hand sides, (RHSCRD = 0) then there is no header line 5, and hence no need to worry about this variable!)

1. F means that all vectors will be listed as "full" vectors, that is, as a list of NROW numbers; M means that, instead, all vectors will be listed in the same format as the matrix. The M option only makes sense if the matrix is being presented in unassembled format.
2. G means that one or more starting guesses or approximate solution vectors are being supplied. If no guess vectors are supplied, this character should be blank (or, actually, anything but a G).
3. X means that one or more exact solution vectors are being supplied. If no exact solution vectors are supplied, leave this character blank.

The Data Records

After the header lines comes data. This data is organized into four distinct sets, of pointers, indices, matrix values, and right hand side information. The number of lines devoted to each set of information were specified in header line number 2. It is common for the final set of data to be omitted. In a few cases, the third set, which describes matrix values, is omitted. In that case, the file only has information about where the nonzero entries of the matrix are, but does not actually specify what those values are. Such a matrix file is called a "pattern" matrix, and in fact, if this is the case, usually the first character of MXTYPE is given as P for "pattern only".

Reference:

1. Iain Duff, Roger Grimes, John Lewis,
   User's Guide for the Harwell-Boeing Sparse Matrix Collection,
   Technical Report TR/PA/92/86,
   CERFACS, October 1992.
   "../../pdf/hbsmc.pdf"
2. Iain Duff, Roger Grimes, John Lewis,
   Sparse Matrix Test Problems,
   ACM Transactions on Mathematical Software,
   Volume 15, Number 1, March 1989, pages 1-14.
3. Web site:
   http://math.nist.gov/MatrixMarket/data/Harwell-Boeing/

Programs to read an HB file include:

• DLAP_IO is a FORTRAN90 library which includes the routine SBHIN, which can read in an HB file;
• SUPER_LU includes routines which can read a real or complex symmetric or unsymmetric assembled HB matrix file;
• HB_IO includes routines which can read a real unsymmetric assembled HB matrix file; It is available in a C++ version, a FORTRAN90 version, and a MATLAB version;

Programs to convert a matrix to an HB file:

• MSM_TO_HB is a MATLAB script which accepts a MATLAB Sparse Matrix and writes it to an HB file;

Programs to convert an HB file to another format:

• HB_TO_MSM is a MATLAB script which reads an HB file and converts the matrix to a MATLAB Sparse Matrix;
• HB_TO_ST is an executable FORTRAN77 program which converts the sparse matrix information stored in a Harwell-Boeing file into a sparse triplet file.

Programs to write an HB file:

• HB_IO includes routines which can write a real unsymmetric assembled HB matrix file; It is available in a C++ version, a FORTRAN90 version, and a MATLAB version;
• MATHEMATICA includes an Export[filename,object] command that can save a matrix object as an HB file.

Sample Files:

• 5by5_rua.hb, a very simple 5 by 5 matrix;
• kershaw_rua.hb, the Kershaw matrix, a 4 by 4 symmetric positive definite matrix for which the incomplete Cholesky factorization fails on a negative pivot;
• the Harwell Boeing Sparse Matrix Collection, contains many (mostly large) examples;

You can go up one level to the DATA page.