Programming Survo in C

Seppo Mustonen : Programming Survo in C

Functions in library SURVO.LIB

matrix_save

Summary

int matrix_save(matr,A,m,n,rlab,clab,lr,lc,type,expr)
char *matr;   /* name of matrix file */
double *A;    /* pointer to matrix */
int m;        /* number of rows */
int n;        /* number of columns */
char *rlab;   /* row labels space */
char *clab;   /* column labels space */
int lr;       /* length of row label */
int lc;       /* length of column label */
int type;     /* type of matrix */
char *expr;   /* matrix expression (internal name) */
int nrem;     /* # of comment lines in edit field */
int remline;  /* first edit line for the comments */

Description

The matrix_save function saves matrix A and its row (rlab) and column (clab) labels in a matrix file *matr. *matr is a pathname with the default path given by the global variable edisk and with the default extension .MAT . The elements of the matrix A are assumed to be in a one-dimensional double array pointed by A by columns.

Each row label has a length of lr bytes and they are in a one-dimensional character array rlab as a contiguous string. Each column label has a length of lc bytes and they are in a one-dimensional character array pointed by clab as a contiguous string.

type is the type of the matrix with possible values of

type=20: diagonal matrix,
type=10: symmetric matrix,
type=0: general matrix,
type=-1: unknown type.

In the last case matrix_save itself determines the type. expr is the internal name of the matrix (as a matrix expression) of a length of 128 characters at most. Also nrem comment lines from the edit field starting from edit line remline can be saved in the matrix file. In case of no comment lines nrem=remline=0.

The matrix file has the following structure:

Header fields:  ERC bytes (ERC=128)
"MATRIX84D m n nrem lr lc type           "

appearing as an ASCII string where the first 10 bytes "MATRIX84D " are for identification and the numeric parameters

# of rows (m)
# of columns (n)
# of comment lines (nrem)
row label length (lr)
column label length (lc)
type of the matrix (type)

have been converted to character strings separated by blanks. The header is followed by:

                                                       offset
Comments: nrem*ERC bytes                                  ERC
Internal name (expr): ERC bytes                  (nrem+1)*ERC
Column labels (*clab): n*lc bytes                (nrem+2)*ERC
Rows of the matrix: lr+8*n bytes each       n*lc+(nrem+2)*ERC

If the matrix is symmetric (type=10), only the elements of the lower triangular part are saved by rows, each row preceded by its label of lr bytes. If the matrix is diagonal (type=20), only the diagonal elements, each preceded by the row label, are saved.

The total size of the matrix file is
m*(lr+8*n)+n*lc+(nrem+2)*ERC bytes for type=0,
m*(lr+8*(m+1)/2)+m*lc+(nrem+2)*ERC bytes for type=10,
m*(lr+8)+m*lc+(nrem+2)*ERC bytes for type=20.

Return Value

matrix_save returns -1 if matrix matr cannot be saved. Otherwise 1 is returned.

Example

double *A;
int m,n;
char *rlab,*clab;
int lr,lc;
int type;
char expr[129];

matrix_save("MEANS",A,m,n,rlab,clab,8,8,-1,expr,0,0);

saves an m*n matrix A in a matrix file MEANS.MAT on the current data disk. The labels of rows are in character array clab and each label has length 8. The labels of columns are in character array rlab and each of them has length 8. The type of matrix is -1 (unknown) and its internal name is expr. No comment lines are saved from the edit field.

Front page of Survo C libraries