RUTHERFORD_BOEING - RB File 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).

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, long *nelt, long *nvar, long *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, long **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 long *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.

Derived types¶

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¶

/* examples/C/rutherford_boeing/rb_read.c
 * Example code for SPRAL_RUTHERFORD_BOEING */
#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;
   long *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);
}

/* examples/C/rutherford_boeing/rb_write.c
 * Example code for SPRAL_RUTHERFORD_BOEING */
#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;
   long 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);
}

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¶