RUTHERFORD_BOEING - RB File Utilities

#include <spral_rutherford_boeing.h> /* or <spral.h> for all packages */

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

void spral_rb_default_read_options(struct spral_rb_read_options *options)

Intialises members of spral_rb_read_options structure to default values.

Parameters:

• options – Structure to be initialised.

void spral_rb_default_write_options(struct spral_rb_write_options *options)

Intialises members of spral_rb_write_options structure to default values.

Parameters:

• options – Structure to be initialised.

int rb_peek(const char *filename, int *m, int *n, int64_t *nelt, int64_t *nvar, int64_t *nval, enum spral_matrix_type *matrix_type, char *type_code, char *title, char *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 – File to read.

• m – If not NULL, set to number of rows in \(A\).

• n – If not NULL, set to number of columns in \(A\).

• nelt – If not NULL, set to number of elements in file. Set to 0 if the matrix is not in elemental format.

• nvar – If not NULL, set to number of row indices in file.

• nval – If not NULL, set to number of reals in file.

• matrix_type – If not NULL, set to type of matrix (see spral_matrix_type). 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 – If not NULL, must point to a length 4 character buffer. Set to the three letter type code from the file (see table).

• title – If not NULL, must point to a length 73 character buffer. Set to the title field of file.

• identifier – If not NULL, must point to a length 9 character buffer. Identifier field of file.

Returns:

Exit status, see table below.

int spral_rb_read(const char *filename, void **handle, enum spral_matrix_type *matrix_type, int *m, int *n, int64_t **ptr, int **row, double **val, const struct spral_rb_read_options *options, char *title, char *identifier, int *state)

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

Warning

Memory is allocated using Fortran routines and stored in handle. The arrays describing the matrix are just pointers into this data structure. It can only be freed using the spral_rb_free_handle() routine, and not by free().

Parameters:

• filename – File to read.

• handle – Handle for underlying memory holding matrix. Must be freed using spral_rb_free_handle() after last access to ptr, row and val.

• matrix_type – Type of matrix to read (see spral_matrix_type). 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.

• m – Number of rows in \(A\).

• n – Number of columns in \(A\).

• ptr – Column pointers (see CSC format). Set to point to an array allocated by the routine. Invalidated when handle is freed.

• row – Row indices (see CSC format). Set to point to an array allocated by the routine. Invalidated when handle is freed.

• val – If not NULL, values of non-zero entries (see CSC format). Set to point to an array allocated by the routine. Invalidated when handle is freed.

• options – Options for reading matrix (see spral_rb_read_options).

• title – If not NULL, must point to a length 73 character buffer. Set to the title field of file.

• identifier – If not NULL, must point to a length 9 character buffer. Identifier field of file.

• state – If not NULL, the random state to use for random number generation (see RANDOM - Pseudo-random number generator).

Returns:

Exit status, see table below.

int spral_rb_read_ptr32(const char *filename, void **handle, enum spral_matrix_type *matrix_type, int *m, int *n, int **ptr, int **row, double **val, const struct spral_rb_read_options *options, char *title, char *identifier, int *state)

As spral_rb_read() except ptr has type int.

Note

This is just a wrapper around the 64-bit call.

Users are encouraged to prefer the 64-bit version.

int spral_rb_write(const char *filename, enum spral_matrix_type matrix_type, int m, int n, const int64_t *ptr, const int *row, const double *val, const struct spral_rb_write_options *options, const char *title, const char *identifier)

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

Parameters:

• filename – File to write. Existing files will be overwritten.

• matrix_type – Type of matrix to write, see enum spral_matrix_type. (will be converted into the second character of the type code).

• m – Number of rows in \(A\).

• n – Number of columns in \(A\).

• ptr[n] – Column pointers (see CSC format).

• row[ptr[n]] – Row indices (see CSC format).

• val[ptr[n]] – Values of non-zero entries (see CSC format). If NULL a pattern only matrix is written.

• options – Options for writing matrix (see spral_rb_write_options).

• title – The title field for the file. Maximum length is 72 characters. Defaults to "Matrix" if NULL.

• identifier – Identifier field of file. Maximum length is 8 characters. Defaults to "0" if NULL.

Returns:

Exit status, see table below.

int spral_rb_write_ptr32(const char *filename, enum spral_matrix_type matrix_type, int m, int n, const int *ptr, const int *row, const double *val, const struct spral_rb_write_options *options, const char *title, const char *identifier)

As spral_rb_write() except ptr has type int.

Note

This is just a wrapper around the 64-bit call.

Users are encouraged to prefer the 64-bit version to ensure support for large matrices.

Return codes

Return 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

typedef struct spral rb_read_options

Specify options for reading matrices.

bool add_diagonal

Add any diagonal entries that are missing if true. Default is false

float extra_space

Proportion of extra space to allow in row[] and val[] arrays. They are allocated to have size options.extra_space * ptr[n]. Default is 1.0.

int lwr_upr_full

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.

Default is 1.

int values

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.

Default is 0.

struct spral_rb_write_options

Specify options for writing matrices.

char val_format[20]

Fortran format string to use when writing values. Should not exceed 80 characters per line. Default is “(3e24.16)”.

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/C/rutherford_boeing/rb_read.c
 * Example code for SPRAL_RUTHERFORD_BOEING */
#include <stdint.h>
#include <stdio.h>
#include "spral.h"

int main(void) {
   /* Matrix data */
   void *handle;
   char title[73]; // Maximum length 72 character + '\0'
   int matrix_type, m, n;
   int64_t *ptr;
   int *row;
   double *val;

   /* Initalise options */
   struct spral_rb_read_options options;
   spral_rb_default_read_options(&options);

   /* Read matrix */
   spral_rb_read("matrix.rb", &handle, &matrix_type, &m, &n, &ptr, &row, &val,
         &options, title, NULL, NULL);

   /* Print matrix */
   printf("Matrix '%s'\n", title);
   spral_print_matrix_i64d(-1, matrix_type, m, n, ptr, row, val, 0);

   /* Free handle */
   spral_rb_free_handle(&handle);
}

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

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

Writing a matrix

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

/* examples/C/rutherford_boeing/rb_write.c
 * Example code for SPRAL_RUTHERFORD_BOEING */
#include <stdint.h>
#include <stdio.h>
#include "spral.h"

int main(void) {
   /* Initialize options */
   struct spral_rb_write_options options;
   spral_rb_default_write_options(&options);

   /* Data for symmetric matrix
    * ( 2  1         )
    * ( 1  4  1    8 )
    * (    1  3  2   )
    * (       2      )
    * (    8       2 ) */
   int n = 5;
   int64_t ptr[]   = { 0,        2,             5,      7,7,   8 };
   int row[]    = { 0,   1,   1,   2,   4,   2,   3,   4   };
   double val[] = { 2.0, 1.0, 4.0, 1.0, 8.0, 3.0, 2.0, 2.0 };

   /* Write matrix */
   spral_rb_write("matrix.rb", SPRAL_MATRIX_REAL_SYM_INDEF, n, n, ptr, row,
      val, &options, "SPRAL_RUTHERFORD_BOEING test matrix", NULL);
}

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.