User-Oriented Modules

The array U(*) should contain an initial approximation to the solution of the linear system before any ITPACK module is called. If the user has no information for making such a guess, then the zero vector may be used as the starting vector. The subroutine VFILL() can be used to fill a vector with a constant:

CALL VFILL (N, U, VAL)

fills the array U(*) of length N with the value VAL in each entry. To aid the user in using the iterative methods of ITPACK, four modules for constructing the sparse matrix storage arrays are included. The modules are:

SBINI()	is called at the beginning to initialize the arrays IA(*), JA(*),
	A(*), and IWORK(*);
SBSIJ()	is called repeatedly to set the individual entries in the matrix and
	build a link list representation of the matrix structure;
SBEND()	is called at the end to restructure the link list into final sparse
	storage form;
SBAGN()	is called to return again to the link list representation if SBEND()
	has been called but additional elements are to be added or modified.

These modules are described below.

(a) Initialization:

CALL SBINI (N,NZ,IA,JA,A,IWORK)

Initializes IA(*), JA(*), A(*), and IWORK(*) for a system of order N. IA(*), JA(*), and IWORK(*) are integer arrays of length at least ${\bf N+1}$, NZ, and NZ, respectively. A(*) is a real array of length at least NZ.

(b) Set individual entries:

CALL SBSIJ (N,NZ,IA,JA,A,IWORK,I,J,VAL,MODE,LEVEL,NOUT,IER)

Inserts the value, VAL, of the (I,J) entry of the user's matrix into the link list representation for that matrix. When using symmetric sparse storage, J must be greater than or equal to I. If the (I,J) entry has already been set then MODE specifies the way in which the entry is to be treated:

${\bf MODE}<0$,	Current entry value is left as is;
=0,	Current entry value is reset to VAL;
>0,	VAL is added to the current entry value.

If LEVEL is less than 0, SBSIJ() causes no printing. If LEVEL is 0, fatal errors messages are written to output unit number NOUT; and if LEVEL is 1 or greater, a message is printed when SBSIJ() encounters a value it has already set with the value being reset according to the value of MODE. IER is an error parameter and returns values of

Error Flag		Meaning
${\bf IER} =$	0,	New (I,J) entry is established.
=	700,	(I,J) entry is already set--reset according to MODE.
=	701,	Improper values for either I or J.
=	702,	NZ is too small--no room for the new entry.

(c) Finalization:

CALL SBEND (N,NZ,IA,JA,A,IWORK)

Restructures the link list data structure built by SBINI() and SBSIJ() into the final data structure required by ITPACK.

(d) Undo Finalization:

CALL SBAGN (N,NZ,IA,JA,A,IWORK,LEVEL,NOUT,IER)

Returns to link list representation for modification or addition of elements to the system. Repeated calls to SBSIJ() can then be made followed by a single call to SBEND() to close-out the sparse matrix representation. If LEVEL is less than 0, no printing is done and if LEVEL is 0 or greater, fatal error information is written to the output unit number NOUT. IER is an error flag indicating:

Error Flag		Meaning
${\bf IER} =$	0,	Successful completion.
=	703,	NZ is too small--no room for the new entry.

Note that SBINI() should not be called after SBAGN() is called since it would destroy the previous data.