LINSOL_FILE_FORMAT - explains the LINSOL_fileformat that is optimally adapted to the data structures used in LINSOL.

LINSOL_FILE_FORMAT 3 "VERSION 1.0" "January 2002"

Table of contents

PURPOSE

The LINSOL_fileformat can be used within the LINSOL program package to read a matrix from a file or to write a matrix to a file. It is possible to read or write an ASCII- or binary-file. The access to the file is always sequential. The matrix used in LINSOL is represented as a triple (mat,index,info) [see also manual page <matrix>]; informations about the array dimensions of the three arrays must be read first.

FIRST RECORD

Thus the first record consists of the five following parameters:

lmat, lindex, l, lsym, nvt

lmat integer, scalar

Length of (local) matrix array MAT.
lindex integer, scalar
Length of the integer array index.
l integer, scalar
Maximal number of unknowns on a processor (it must hold: l = max{lmatbk(i),i=1,..,nproc}).
lsym logical, scalar
is .true., if the matrix MAT is symmetric; is .false., if the matrix MAT is non-symmetric;
nvt integer, scalar
Number of vector terms the matrix MAT consists of [see also manual page <lsolp> and <matrix>].

SECOND [or (2+loops)th] RECORD

The second or (2+loops)th record consists of two parameters:

ityp, nvecterms

ityp integer, scalar is the number of the storage pattern to be read (written). 

     ityp = 1	 :    read (write) main	diagonal,
     ityp = 2	 :    read (write) full	diagonal(s),
     ityp = 3	 :    read (write) packed diagonal(s),
     ityp = 6	 :    read (write) starry sky (skies),
     ityp = 7	 :    read (write) full	row(s),
     ityp = 8	 :    read (write) full	column(s),
     ityp = 9	 :    read (write) packed row(s),
     ityp =11	 :    read (write) packed column(s).
nvecterms integer, scalar
is the number of vector terms of a certain storage pattern determined by ityp to read (write). If ityp = 1 holds, nvecterms can only be set to 1 (is is not allowed to define more than one main diagonal!).

The composition and number of the next records depend on the type of the storage pattern;

ONE RECORD FOR THE MAIN DIAGONAL

if (ityp == 1) holds, then the next record consists of the main diagonal elements:

vtmain(1), vtmain(2), ..., vtmain(l)

vtmain(1..l) double precision, vector

The main diagonal elements must be read (written).

TWO RECORDS FOR FULL DIAGONALS, FULL ROWS AND FULL COLUMNS

if ((ityp == 2) .or. (ityp == 7) .or. (ityp == 8)) holds, then read (write) nvecterms times the following two records:

lvt, iac, iar

vtfull(1), vtfull(2), ..., vtfull(lvt)

lvt integer, scalar

The length of the next vector term to be read (written).
iac integer, scalar
{The column index of the first element of the next vector term to be read (written)} - 1.
iar integer, scalar
{The row index of the first element of the next vector term to be read (written)} - 1.
vtfull(1..lvt) double precision, vector
The elements of a full vector term must be read (written).

THREE RECORDS FOR PACKED DIAGONALS, PACKED ROWS AND PACKED COLUMNS

if ((ityp == 3) .or. (ityp == 9) .or. (ityp == 11))) holds, then read (write) nvecterms times the following three records:

lvt, iac, iar

index(1), index(2), ..., index(lvt)

vtpack(1), vtpack(2), ..., vtpack(lvt)

lvt integer, scalar

The length of the next vector term to be read (written).
iac integer, scalar
{The column index of the first element of the next vector term to be read (written)} - 1.
iar integer, scalar
{The row index of the first element of the next vector term to be read (written)} - 1.
index(1..lvt) integer, vector
The indices of a packed vector term must be read (written).
vtpack(1..lvt) double precision, vector
The elements of a packed vector term must be read (written).

FOUR RECORDS FOR STARRY SKY

if (ityp == 6) holds, then read (write) nvecterms times the following four records:

lvt

cindex(1), cindex(2), ..., cindex(lvt)

rindex(1), rindex(2), ..., rindex(lvt)

vtpack(1), vtpack(2), ..., vtpack(lvt)

lvt integer, scalar

The length of the next vector term to be read (written).
cindex(1..lvt) integer, vector
The column indices of a packed vector term must be read (written).
rindex(1..lvt) integer, vector
The row indices of a packed vector term must be read (written).
vtpack(1..lvt) double precision, vector
The elements of a packed vector term must be read (written).
If the matrix is composed of different storage patterns, then goto 2[+loops]th record to read the next vector terms of a different storage pattern. Remark: loops is equal to the number of records read by the actually defined storage pattern and the previous ones.

ROUTINE LININ

You can use the routine LININ to load a matrix stored in LINSOL- fileformat. The access to the file is sequential and unformatted; thus the file must be an ASCII-file and the elements of the matrix must be stored as double precision values. The routine LININ is a member of the library liblinsol.a. The syntax of the routine is:

call LININ(MAT,lmat,index,lindex,info,ia1,nvt,lloc,l,lsym,

unit,lout,ierr)

integer, parameter :: ia2 = 7

integer, intent(in) :: ia1,unit,l,lout

integer, intent(inout) :: lmat,lindex

integer, intent(out) :: nvt,ierr,lloc

integer, intent(out) :: info(ia1,ia2)

integer, intent(out) :: index(lindex)

double precision, intent(out) :: MAT(lmat)

logical, intent(out) :: lsym

MAT double precision, array: MAT(lmat), output
Matrix array.
lmat integer, scalar, input/output
Length of (local) matrix array MAT.
index integer, array: index(lindex), output
Array of indices enabling indirect access to the matrix array MAT.
lindex integer, scalar, input/output
Length of the integer array index.
info integer, array: info(ia1,ia2), output
Information array for the matrix MAT (ia2 {= 7} is a constant).
ia1 integer, scalar, input
First dimension of matrix information array info.
nvt , integer, scalar, output
Number of used vector terms.
lloc integer, scalar, output
Number of rows and columns respectively of the matrix.
l integer, scalar, input
Number of rows and columns respectively of the matrix. If l <> lloc, then the routine stops with an error.
lsym logical, scalar, input
is .true., if the matrix MAT is symmetric, is .false., if the matrix MAT is non-symmetric.
unit integer, scalar, input
I/O-unit to read from.
lout integer, scalar, input
is the number of the output device of messages (stdout is 6).
ierr integer, scalar, output
is an error indicator (ierr <> 0 --> error occured).

ROUTINE LINBIN

You can use the routine LINBIN to load a matrix stored in LINSOL- fileformat. The access to the file is sequential and formatted; the file must be an binary file and the elements of the matrix must be stored as single precision values. The routine LINBIN is a member of the library liblinsol.a. The syntax of the routine is:

call LINBIN(MAT,lmat,index,lindex,info,ia1,nvt,lloc,l,lsym,

unit,lout,ierr)

integer, parameter :: ia2 = 7

integer, intent(in) :: ia1,unit,l,lout

integer, intent(inout) :: lmat,lindex

integer, intent(out) :: nvt,ierr,lloc

integer, intent(out) :: info(ia1,ia2)

integer, intent(out) :: index(lindex)

real*4, intent(out) :: MAT(lmat)

logical, intent(out) :: lsym

MAT real*4, array: MAT(lmat), output
Matrix array.

All other arguments can you see above.

ROUTINE LINOUT

You can use the routine LINOUT to store a matrix defined as triple (mat,index,info) due to the specifications in the manual page <matrix> in the LINSOL-fileformat. The resulting file is sequential and unformatted; thus the file is an ASCII-file and the elements of the matrix are being stored as double precision values. The routine LINOUT is a member of the library liblinsol.a. The syntax of the routine is:

call LINOUT(MAT,lmat,index,lindex,info,ia1,nvt,l,lsym,

ilin,unit,ierr)

integer, parameter :: ia2 = 7, nilin = 50

integer, intent(in) :: ia1,unit,l

integer, intent(in) :: lmat,lindex,nvt

integer, intent(out) :: ierr

integer, intent(in) :: info(ia1,ia2)

integer, intent(in) :: index(lindex)

integer, intent(in) :: ilin(nilin)

double precision, intent(in) :: MAT(lmat)

logical, intent(in) :: lsym

ilin integer, array: ilin(nilin), input
Information vector (nilin {=50} is a constant); the values of ilin(12), ilin(13), ilin(17), ilin(33), ilin(34) must be set due to the manual page <lsolp> for a correct use of this routine.
unit integer, scalar, input
I/O-unit to write to.

All other arguments can you see above.

ROUTINE LINBOUT

You can use the routine LINBOUT to store a matrix defined as triple (mat,index,info) due to the specifications in the manual page <matrix> in the LINSOL-fileformat. The resulting file is sequential and formatted; the resulting file is an binary file and the elements of the matrix are being stored as single precision values. The routine LINBOUT is a member of the library liblinsol.a. The syntax of the routine is:

call LINBOUT(MAT,lmat,index,lindex,info,ia1,nvt,l,lsym,

ilin,unit,ierr)

integer, parameter :: ia2 = 7, nilin = 50

integer, intent(in) :: ia1,unit,l

integer, intent(in) :: lmat,lindex,nvt

integer, intent(out) :: ierr

integer, intent(in) :: info(ia1,ia2)

integer, intent(in) :: index(lindex)

integer, intent(in) :: ilin(nilin)

real*4, intent(in) :: MAT(lmat)

logical, intent(in) :: lsym

ilin integer, array: ilin(nilin), input
Information vector (nilin {=50} is a constant); the values of ilin(12), ilin(13), ilin(17), ilin(33), ilin(34) must be set due to the manual page <lsolp> for a correct use of this routine.
unit integer, scalar, input
I/O-unit to write to.

All other arguments can you see above.

PROGRAMMERS / CONSULTING

Original Program by H. Haefner 1998-99

Consulting by 

     Numerikforschung fuer Supercomputer
     Rechenzentrum der Universitaet Karlsruhe
     Am	Zirkel 2
     D-76128 Karlsruhe
     Germany
     Tel.      :   (+721) 608/4869
     Fax.      :   (+721) 32550
     e-mail    :   haefner@rz.uni-karlsruhe.de