spral_rutherford_boeing - RB File Format Utilities

Purpose

This package provides routines to read and write matrices stored in files using the Rutherford-Boeing format.

At present, reading and writing of supplementary data (e.g. right-hand sides) is not supported. If it is required to read and write these files, we recommend the use of the HSL routines MC55 and MC56 that are available without charge (although redistribution is not permitted).

Version history

2016-09-08 Version 1.0.0

Initial release.

[For detailed history, see ChangeLog]

Subroutines

subroutine  rb_peek(filename, inform[, m, n, nelt, nvar, nval, matrix_type, type_code, title, identifier])

Returns information about a matrix \(A\) stored in a specified file using Rutherford Boring format (only information from the file header is accessed).

Parameters:

• filename [character(len=*),in] :: File to read.

• inform [integer ,out] :: Exit status, see table below.

Options:

• m [integer ,out] :: Number of rows in \(A\).

• n [integer ,out] :: Number of columns in \(A\).

• nelt [integer(long),out] :: Number of elements in file if matrix is stored in elemental format, or 0 otherwise.

• nvar [integer(long),out] :: Number of row indices in file.

• nval [integer(long),out] :: Number of reals in file.

• matrix_type [integer ,out] :: Type of matrix, one of the values defined in spral_matrix_util. Note that RB files do not distguish between symmetric positive-definite and symmetric indefinite matrices, so the latter matrix type is used for all symmetric matrices.

• type_code [character(len=3),out] :: The three letter type code from the file (see table).

• title [character(len=72),out] :: Title field of file, usually the matrix name.

• identifier [character(len=8),out] :: Identifier field of file, usually an id number.

Note

An alternate version of this routine is also available that accepts a unit number instead of a filename, refer to source code if required.

subroutine  rb_read(filename, m, n, ptr, row, val, options, inform[, matrix_type, type_code, title, identifier, state])

Reads a CSC matrix from a file stored in RB format.

Parameters:

• filename [character(len=*),in] :: File to read.

• m [integer ,out] :: Number of rows in \(A\).

• n [integer ,out] :: Number of columns in \(A\).

• ptr (*) [integer(long),allocatable, out] :: Column pointers (see CSC format). Will be allocated by the routine to have sufficient size.

• row (*) [integer ,allocatable, out] :: Row indices (see CSC format). Will be allocated by the routine to have sufficient size.

• val (*) [real ,allocatable, out] :: Values of non-zero entries (see CSC format) if present and requested. Will be allocated by the routine to have sufficient size.

• options [rb_read_options ,in] :: Options for reading matrix (see rb_read_options).

• inform [integer ,out] :: Exit status, see table below.

Options:

• matrix_type [integer ,out] :: Type of matrix, one of the values defined in spral_matrix_util. Note that RB files do not distguish between symmetric positive-definite and symmetric indefinite matrices, so the latter matrix type is used for all symmetric matrices.

• type_code [character(len=3),out] :: The three letter type code from the file (see table).

• title [character(len=72),out] :: Title field of file.

• identifier [character(len=8),out] :: Identifier field of file.

• state [random_state ,inout] :: Random state to use for random number generation (if required).

Note

A version with ptr(:) as default integer is also supplied, but users are recommended to use the long integer version to ensure support for large matrices.

subroutine  rb_write(filename, matrix_type, m, n, ptr, row, options, inform[, val, title, identifier])

Writes a CSC format matrix to the specified file in RB format.

Parameters:

• filename [character(len=*),in] :: File to write. Any existing file will be overwritten.

• matrix_type [integer ,in] :: Type of matrix to write, one of the values defined in spral_matrix_util (will be converted into the second character of the type code).

• m [integer ,in] :: Number of rows in \(A\).

• n [integer ,in] :: Number of columns in \(A\).

• ptr (n+1) [integer(long),in] :: Column pointers (see CSC format).

• row (ptr(n+1)-1) [integer ,in] :: Row indices (see CSC format).

• options [rb_write_options ,in] :: Options for writing matrix (see rb_write_options).

• inform [integer ,out] :: Exit status, see table below.

Options:

• val (ptr(n+1)-1) [real ,in] :: Values of non-zero entries (see CSC format).

• title [character(len=*),in] :: Title field of file. Maximum length is 72 characters. Defaults to "Matrix" if not present.

• identifier [character(len=*),in] :: Identifier field of file. Maximum length is 8 characters. Defaults to "0" if not present.

Note

A version with ptr(:) as default integer is also supplied, but users are recommended to use the long integer version to ensure support for large matrices.

Exit status codes

Exit status codes

inform	Status
0	Success
-1	Failed to open file.
-2	Not a valid Rutherford-Boeing file.
-3	Error on i/o operation.
-4	Attempted to read data type not supported by routine.
-5	Attempted to read matrix in elemental format.
-6	Invalid matrix type.
-10	options%extra_space<1.0.
-11	options%lwr_upr_full has invalid value.
-12	options%values has invalid value.
-20	Memory allocation failed.
+1	Values are stored in an auxiliary file (not read)

Derived types

type  rb_read_options

Specify options for reading matrices.

Type fields:

• % add_diagonal [logical ,default=.false.] :: Add any diagonal entries that are missing.

• % extra_space [real ,default=1.0] :: Proportion of extra space to allow in row(:) and val(:) arrays. They are allocated to have size options%extra_space * (ptr(n+1)-1).

• % lwr_upr_full [integer ,default=1] ::

  Return lower triangle, upper triangle or both for symmetric and skew-symmetric matrices. One of:

  1 (default)	Lower triangular entries only.
  2	Upper triangular entries only.
  3	Both lower and upper triangular entries.

• % values [integer ,default=0] ::

  Whether to read and/or generate values. One of:

  0 (default)	Read values from file, only if present.
  1	Do not read or generate value, return pattern only.
  2	Read values from file. If no values are present, randomly generate symmetric values.
  3	Read values from file. If no values are present, randomly generate symmetric, diagonally dominant values.
  4	Read values from file. If no values are present, randomly generate (unsymmetric) values.
  -2	Randomly generate symmetric values. Any values in file are ignored.
  -3	Randomly generate symmetric, diagonally dominant values. Any values in file are ignored.
  -4	Randomly generate (unsymmetric) values. Any values in file are ignored.

type  rb_write_options

Specify options for writing matrices.

Type fields:

• % val_format [character(len=20),default=”(3e24.16)”] :: Fortran format string to use when writing values. Should not exceed 80 characters per line.

Note

Formats for integer data will be automatically determined based on the maximum values to be represented.

Example

Reading a matrix

The following code reads a matrix from the file “matrix.rb”:

! examples/Fortran/rutherford_boeing/rb_read.f90
! Example code for SPRAL_RUTHERFORD_BOEING
program rb_read_example
   use spral_rutherford_boeing
   use spral_matrix_util, only: print_matrix, &
                                SPRAL_MATRIX_REAL_SYM_INDEF
   implicit none

   ! Parameters
   integer, parameter :: long = selected_int_kind(18)
   integer, parameter :: wp = kind(0d0)

   ! Matrix data
   character(len=72) :: title
   integer :: m, n
   integer(long), dimension(:), allocatable :: ptr
   integer, dimension(:), allocatable :: row
   real(wp), dimension(:), allocatable :: val

   ! rb_read options and inform
   type(rb_read_options) :: options
   integer :: inform

   ! Read matrix
   call rb_read("matrix.rb", m, n, ptr, row, val, options, inform, &
      title=title)

   ! Print matrix
   write(*, "(3a)") "Matrix '", trim(title), "'"
   call print_matrix(6, -1, SPRAL_MATRIX_REAL_SYM_INDEF, m, n, ptr, row, val)

end program rb_read_example

This produces the following output, when run on the file generated by the rb_write.f90 example in the next section:

Matrix 'SPRAL_RUTHERFORD_BOEING test matrix'
Real symmetric indefinite matrix, dimension 5x5 with 8 entries.
1:   2.0000E+00   1.0000E+00
2:   1.0000E+00   4.0000E+00   1.0000E+00                8.0000E+00
3:                1.0000E+00   3.0000E+00   2.0000E+00
4:                             2.0000E+00
5:                8.0000E+00                             2.0000E+00

Writing a matrix

The following code writes a matrix to the file “matrix.rb”:

! examples/Fortran/rutherford_boeing/rb_write.f90
! Example code for SPRAL_RUTHERFORD_BOEING
program rb_write_example
   use spral_rutherford_boeing
   use spral_matrix_util, only: SPRAL_MATRIX_REAL_SYM_INDEF
   implicit none

   ! Parameters
   integer, parameter :: long = selected_int_kind(18)
   integer, parameter :: wp = kind(0d0)

   ! Matrix data
   integer :: n
   integer(long) :: ptr(6)
   integer :: row(8)
   real(wp) :: val(8)

   ! rb_read options and inform
   type(rb_write_options) :: options
   integer :: inform

   ! Data for symmetric matrix
   ! ( 2  1         )
   ! ( 1  4  1    8 )
   ! (    1  3  2   )
   ! (       2      )
   ! (    8       2 )
   n = 5
   ptr(1:n+1)        = (/ 1,        3,             6,      8,8,   9 /)
   row(1:ptr(n+1)-1) = (/ 1,   2,   2,   3,   5,   3,   4,   5   /)
   val(1:ptr(n+1)-1) = (/ 2.0, 1.0, 4.0, 1.0, 8.0, 3.0, 2.0, 2.0 /)

   ! Write matrix
   call rb_write("matrix.rb", SPRAL_MATRIX_REAL_SYM_INDEF, n, n, ptr, row, &
      options, inform, val=val, title="SPRAL_RUTHERFORD_BOEING test matrix")

end program rb_write_example

This produces the following file:

SPRAL_RUTHERFORD_BOEING test matrix                                     0
             5             1             1             3
rsa                        5             5             8             0
(40i2)          (40i2)          (3e24.16)
 1 3 6 8 8 9
 1 2 2 3 5 3 4 5
  0.2000000000000000E+01  0.1000000000000000E+01  0.4000000000000000E+01
  0.1000000000000000E+01  0.8000000000000000E+01  0.3000000000000000E+01
  0.2000000000000000E+01  0.2000000000000000E+01

Method

Generation of random values

Values are generated uniformly at random from \([-1,1]\). If a diagonally dominant matrix is requested, the diagonal entry in each row is set to \(\max(100, 10k)\), where k is the number of entries in the column.

If a random state is not provided by the user, the default initial state from the spral_random module is used.

Rutherford Boeing File format

The Rutherford Boeing file format is described in the following report [1]. A file may either contain a sparse matrix or supplementary data. However, this package only supports the former.

Sparse matrices are stored in either CSC format or Elemental format. A three letter type code is used to encodes this and additional information, as per the following table:

Type code

First character	Second character	Third character
r: real	s: symmetric	a: CSC format
c: complex	u: unsymmetric	e: Elemental format
i: integer	h: Hermitian
p: pattern	z: skew symmetric
q: pattern	r: rectangular

The difference between the p and q pattern types is that the latter indicates that values are supplied in an auxiliary file (this package does not support reading such files).

Further information may be found in:

[1]

I.S. Duff, R.G. Grimes and J.G. Lewis (1997). The Rutherford-Boeing Sparse Matrix Collection. RAL Technical Report RAL-TR-97-031.