The user's matrix is passed to BlockSolve in the following format. The matrix data structure is represented in the structure BSspmat and each row of the matrix is represented by the structure BSsprow. We believe that this format is flexible enough to be used in a variety of contexts. We had no difficulty in writing a C interface routine to take a matrix written in a standard sequential format by a Fortran code and put this structure around it without duplicating the data in the Fortran sparse matrix.
typedef struct __BSsprow {
int diag_ind; /* index of diagonal in row */
int length; /* num. of nz in row */
int *col; /* col numbers */
double *nz; /* nz values */
} BSsprow;
typedef struct __BSspmat {
int num_rows; /* number of local rows */
int global_num_rows;/* number of global rows */
BSmapping *map; /* mapping from local to global, etc */
BSsprow **rows; /* the sparse rows */
} BSspmat;
First, we address the structure BSspmat. The field num_rows contains the number of rows local to the processor. The field global_num_rows contains the total number of rows in the linear system. The field map contains mapping information that will be discussed later. The field rows is an array of pointers to local rows of the sparse matrix.
In the structure BSsprow, the field diag_ind is the index of the diagonal in this row. We require that every row have a diagonal element (the value of this element could be zero). The field length contains the number of nonzero values in this row. The field col is a pointer to an array of integer values that represent the column number of each nonzero value in the row. These column numbers must be sorted in ascending order. The field nz is a pointer to an array of double-precision values that are the nonzero values in the row.
The mapping structure serves three purposes: (1) the mapping of local row number to global row numbers, (2) the mapping of global row numbers to local row numbers, and (3) the mapping of global row number to processor number. We provide routines for the user to set up and perform this mapping (details on these routines are given in the ``man'' pages). The user is free, however, to setup his own mapping and use his own routines through this data structure. The local row numbers on every processor run from 0 to num_rows-1; the global row numbers run from 0 to global_num_rows-1. Each local row has a corresponding global row number.
typedef struct __BSmapping {
void *vlocal2global; /* data for mapping local to global */
void (*flocal2global)(); /* a function for mapping local to global */
void (*free_l2g)(); /* a function for free'ing the l2g data */
void *vglobal2local; /* data for mapping global to local */
void (*fglobal2local)(); /* a function mapping global to local */
void (*free_g2l)(); /* a function for free'ing the g2l data */
void *vglobal2proc; /* data for mapping global to proc */
void (*fglobal2proc)(); /* a function mapping global to proc */
void (*free_g2p)(); /* a function for free'ing the g2p data */
} BSmapping;
The field vlocal2global is a pointer to data that is passed into the local to global mapping function (if the user is doing the mapping, he is free to make this point to whatever he wishes). The field flocal2global is a pointer to a function for performing the local to global mapping. The field free_l2g is a pointer to a function for freeing the data in the field vlocal2global. The function for performing the local to global mapping takes 5 arguments:
int length; /* the number of row numbers to translate */ int *req_array; /* the array of local row numbers to translate */ int *ans_array; /* the array of corresponding global row numbers */ BSprocinfo *procinfo; /* the processor information context */ BSmapping *map; /* the mapping data structure */
The next three fields (,
, and
) are exactly the same except
the mapping is from global to local row number. The mapping is
performed only for rows that are local to the processor; if the mapping
is attempted for a nonlocal global row number, then a value of
-1 is placed in the ans_array. The arguments to the mapping function
are
int length; /* the number of row numbers to translate */ int *req_array; /* the array of global row numbers to translate */ int *ans_array; /* the array of corresponding local row numbers */ BSprocinfo *procinfo; /* the processor information context */ BSmapping *map; /* the mapping data structure */
The last three fields (,
, and
) are exactly the same except
the mapping is from global row number to processor number.
The arguments to the mapping function
are:
int length; /* the number of row numbers to translate */ int *req_array; /* the array of global row numbers to translate */ int *ans_array; /* the array of corresponding processor numbers */ BSprocinfo *procinfo; /* the processor information context */ BSmapping *map; /* the mapping data structure */