Chapter 14: Printing Functions

write_matrix

Prints a rectangular matrix (or vector) stored in contiguous memory locations.

Synopsis

#include <imsls.h>

void imsls_f_write_matrix (char *title, int nra, int nca, float a[], …, 0)

For int a[], use imsls_i_write_matrix.
For double a[], use imsls_d_write_matrix.

Required Arguments

char *title   (Input)
Matrix title. Use \n within a title to create a new line. Long titles are automatically wrapped.

int nra   (Input)
Number of rows in the matrix.

int nca   (Input)
Number of columns in the matrix.

float a[]   (Input)
Array of size nra Χ nca containing the matrix to be printed.

Synopsis with Optional Arguments

#include <imsls.h>

void imsls_f_write_matrix (char *title, int nra, int nca, float a[],
IMSLS_TRANSPOSE,
IMSLS_A_COL_DIM, int a_col_dim,
IMSLS_PRINT_ALL, or
IMSLS_PRINT_LOWER, or
IMSLS_PRINT_UPPER, or
IMSLS_PRINT_LOWER_NO_DIAG, or
IMSLS_PRINT_UPPER_NO_DIAG,
IMSLS_WRITE_FORMAT, char *fmt,
IMSLS_NO_ROW_LABELS, or
IMSLS_ROW_NUMBER, or
IMSLS_ROW_NUMBER_ZERO, or
IMSLS_ROW_LABELS, char *rlabel[],
IMSLS_NO_COL_LABELS, or
IMSLS_COL_NUMBER, or
IMSLS_COL_NUMBER_ZERO, or
IMSLS_COL_LABELS, char *clabel[],
0)

Optional Arguments

IMSLS_TRANSPOSE
Print aT.

IMSLS_A_COL_DIM, int a_col_dim   (Input)
Column dimension of a.
Default: a_col_dim = nca

IMSLS_PRINT_ALL, or

IMSLS_PRINT_LOWER, or

IMSLS_PRINT_UPPER, or

IMSLS_PRINT_LOWER_NO_DIAG, or

IMSLS_PRINT_UPPER_NO_DIAG
Exactly one of these optional arguments can be specified to indicate that either a triangular part of the matrix or the entire matrix is to be printed. If omitted, the entire matrix is printed.

Keyword

Action

IMSLS_PRINT_ALL

Entire matrix is printed (the default).

IMSLS_PRINT_LOWER

Lower triangle of the matrix is printed, including the diagonal.

IMSLS_PRINT_UPPER

Upper triangle of the matrix is printed, including the diagonal.

IMSLS_PRINT_LOWER_NO_DIAG

Lower triangle of the matrix is printed, without the diagonal.

IMSLS_PRINT_UPPER_NO_DIAG

Upper triangle of the matrix is printed, without the diagonal.

IMSLS_WRITE_FORMAT, char *fmt   (Input)
Character string containing a list of C conversion specifications (formats) to be used when printing the matrix. Any list of C conversion specifications suitable for the data type can be given. For example, fmt = "%10.3f" specifies the conversion character f for the entire matrix. For the conversion character f, the matrix must be of type float or double. Alternatively,fmt = "%10.3e%10.3e%10.3f%10.3f%10.3f" specifies the conversion character e for columns 1 and 2 and the conversion character f for columns 3, 4, and 5. If the end of fmt is encountered and if some columns of the matrix remain, format control continues with the first conversion specification in fmt.

            Aside from restarting the format from the beginning, other exceptions to the usual C formatting rules are as follows:

            Characters not associated with a conversion specification are not allowed. For example, in the format fmt = "1%d2%d", the characters 1 and 2 are not allowed and result in an error.

            A conversion character d can be used for floating-point values (matrices of type float or double). The integer part of the floating-point value is printed.

            For printing numbers whose magnitudes are unknown, the conversion character g is useful; however, the decimal points will generally not be aligned when printing a column of numbers. The w (or W) conversion character is a special conversion character used by this function to select a conversion specification so that the decimal points will be aligned. The conversion specification ending with w is specified as "%n.dw". Here, n is the field width and d is the number of significant digits generally printed. Valid values for n are 3, 4, …, 40. Valid values for d are 1, 2, …, n  2. If fmt specifies one conversion specification ending with w, all elements of a are examined to determine one conversion specification for printing. If fmt specifies more than one conversion specification, separate conversion specifications are generated for each conversion specification ending with w. Set fmt = "10.4w" for a single conversion specification selected automatically with field width 10 and with four significant digits.

IMSLS_NO_ROW_LABELS, or

IMSLS_ROW_NUMBER, or

IMSLS_ROW_NUMBER_ZERO, or

IMSLS_ROW_LABELS, char *rlabel[]   (Input)
If IMSLS_ROW_LABELS is specified, rlabel is a vector of length nra containing pointers to the character strings comprising the row labels. Here, nra is the number of rows in the printed matrix. Use \n within a label to create a new line. Long labels are automatically wrapped. If no row labels are desired, use the IMSLS_NO_ROW_LABELS optional argument. If the numbers 1, 2,  …, nra are desired, use the IMSLS_ROW_NUMBER optional argument. If the numbers 0, 1, 2, …, nra  1 are desired, use the IMSLS_ROW_NUMBER_ZERO optional argument. If none of these optional arguments is used, the numbers 1, 2, 3, …, nra are used for the row labels by default whenever nra > 1.
If nra = 1, the default is no row labels.

IMSLS_NO_COL_LABELS, or

IMSLS_COL_NUMBER, or

IMSLS_COL_NUMBER_ZERO, or

IMSLS_COL_LABELS, char *clabel[]   (Input)
If IMSLS_COL_LABELS is specified, clabel is a vector of length nca + 1 containing pointers to the character strings comprising the column headings. The heading for the row labels is clabel [0]; clabel [i], i = 1, …, nca, is the heading for the i-th column. Use \n within a label to create a new line. Long labels are automatically wrapped. If no column labels are desired, use the IMSLS_NO_COL_LABELS optional argument. If the numbers 1, 2, …, nca, are desired, use the IMSLS_COL_NUMBER optional argument. If the numbers 0, 1, …, nca  1 are desired, use the IMSLS_COL_NUMBER_ZERO optional argument. If none of these optional arguments is used, the numbers 1, 2, 3, …, nca are used for the column labels by default whenever nca > 1. If nca = 1, the default is no column labels.

Description

Function imsls_write_matrix prints a real rectangular matrix (stored in a) with optional row and column labels (specified by rlabel and clabel, respectively, regardless of whether a or aT is printed). An optional format, fmt, can be used to specify a conversion specification for each column of the matrix.

In addition, the write matrix functions can restrict printing to the elements of the upper or lower triangles of a matrix by using the IMSLS_PRINT_UPPER, IMSLS_PRINT_LOWER, IMSLS_PRINT_UPPER_NO_DIAG, and IMSLS_PRINT_LOWER_NO_DIAG options. Generally, these options are used with symmetric matrices, but this is not required. Vectors can be printed by specifying a row or column dimension of 1.

Output is written to the file specified by the function imsls_output_file (Chapter 15, “Utilities”);. The default output file is standard output (corresponding to the file pointer stdout). A page width of 78 characters is used. Page width and page length can be reset by invoking function imsls_page.

Horizontal centering, the method for printing large matrices, paging, the method for printing NaN (Not a Number), and whether or not a title is printed on each page can be selected by invoking function imsls_write_options.

Examples

Example 1

This example is representative of the most common situation in which no optional arguments are given.

#include <imsls.h>

 

#define NRA 3

#define NCA 4

 

int main()

{

    int     i, j;

    float   a[NRA][NCA];

 

    for (i = 0; i < NRA; i++) {

        for (j = 0; j < NCA; j++) {

            a[i][j] = (i+1+(j+1)*0.1);

        }

 

    }

                                /* Write matrix */

    imsls_f_write_matrix ("matrix\na", NRA, NCA, (float*) a, 0);

}

Output

                     Matrix

                        A

            1           2           3           4

1         1.1         1.2         1.3         1.4

2         2.1         2.2         2.3         2.4

3         3.1         3.2         3.3         3.4

Example 2

In this example, some of the optional arguments available in the imsls_write_matrix functions are demonstrated.

#include <imsls.h>

 

#define NRA     3

#define NCA     4

 

int main()

{

    int         i, j;

    float       a[NRA][NCA];

    char        *fmt = "%10.6W";

    char        *rlabel[] = {"row 1", "row 2", "row 3"};

    char        *clabel[] = {"", "col 1", "col 2", "col 3", "col 4"};

 

    for (i = 0; i < NRA; i++) {

        for (j = 0; j < NCA; j++) {

            a[i][j] = (i+1+(j+1)*0.1);

        }

    }

                                /* Write matrix */

    imsls_f_write_matrix ("matrix\na", NRA, NCA, (float *)a,

        IMSLS_WRITE_FORMAT, fmt,

        IMSLS_ROW_LABELS, rlabel,

        IMSLS_COL_LABELS, clabel,

        IMSLS_PRINT_UPPER_NO_DIAG,

        0);

}

Output

                       Matrix

                          a

            col 2       col 3       col 4           

row 1         1.2         1.3         1.4           

row 2                     2.3         2.4           

row 3                                 3.4           

Example 3

In this example, a row vector of length four is printed.

#include <imsls.h>

 

#define NRA 1

#define NCA 4

 

int main()

{

    int         i;

    float       a[NCA];

    char        *clabel[] = {"", "col 1", "col 2", "col 3", "col 4"};

 

    for (i = 0; i < NCA; i++) {  

    a[i] = i + 1;

   }

                                /* Write matrix */

    imsls_f_write_matrix ("matrix\na", NRA, NCA, a,

        IMSLS_COL_LABELS, clabel,

        0);

}

Output

                    Matrix

                       a

     col 1       col 2       col 3       col 4

         1           2           3           4


Visual Numerics, Inc.
Visual Numerics - Developers of IMSL and PV-WAVE
http://www.vni.com/
PHONE: 713.784.3131
FAX:713.781.9260