C2.03. FMS Subroutine FMSOS

FMSOS

PURPOSE: Open Submatrix File

To open a file for storing submatrices.

SYNOPSIS


CALL FMSOS (LENR, LENI, LENV, NUMVEC, NUMSUB, NAME, LUS)

INPUT PARAMETERS:

LENR = Integer.
Record length for matrix file in units of REAL*8 words.
>0, use fixed length records. If M is the dimension of the largest submatrix on the file, then LENR must be at least the following:

Submatrix
Format Data
Type LENR
1,2 (full) Real M*M
1,2 (full) Complex 2*M*M
3,4 (triangular) Real M*(M+1)/2
3,4 (triangular) Complex M*(M+1)
5 (row) Real M
5 (row) Complex 2*M

<= 0, use variable length records.
LENI = Integer.
Record length for integer file in units of integers.
>0, use fixed length records. If M is the dimension of the largest submatrix on the file, then LENI must be at least (M+2).
<= 0, use variable length record files.
LENV = Integer.
Record length for vector file in units of REAL*8 words.
>0, use fixed length records. If M is the dimension of the largest submatrix on the file, then LENV must be at least NUMVEC*M for real data, 2*NUMVEC*M for complex data.
<= 0, use variable length record files.
NUMVEC = Integer.
Number of vectors on vector file.
= 0, do not use vector file.
NUMSUB = Integer.
Number of records.
NAME = Character string.
A 1 to 119 character string that contains a unique name for the submatrix file. FMS appends an 'R' to this name for the matrix file, an 'I' for the integer file and a 'S' for the vector file.

Submatrix Format	Data Type	LENR
1,2 (full)	Real	M*M
1,2 (full)	Complex	2MM
3,4 (triangular)	Real	M*(M+1)/2
3,4 (triangular)	Complex	M*(M+1)
5 (row)	Real	M
5 (row)	Complex	2*M

OUTPUT PARAMETERS:

LUS(25) = Integer array.
FMS Submatrix File Attribute List for the new submatrix file.

FMS PARAMETERS:

The following FMS Parameters are especially important to this routine:

Parameter Description
IEXIST Use existing file
INCORE File location (disk or memory)
LBUFSI Buffer size for submatrix integer records
LBUFSR Buffer size for submatrix real records
LBUFSV Buffer size for submatrix vector records

Parameter	Description
IEXIST	Use existing file
INCORE	File location (disk or memory)
LBUFSI	Buffer size for submatrix integer records
LBUFSR	Buffer size for submatrix real records
LBUFSV	Buffer size for submatrix vector records

DESCRIPTION:

Submatrix Files pass submatrix data to the FMS assembly process. Finite element programs use submatrix files when FMS performs the global matrix assembly.

You may create multiple submatrix files by calling this subroutine more than once. The submatrix file attributes, however, must be stored in a single array LUS(25,NUMSF). On each call, i, you pass the attribute list for that submatrix file, LUS(1,i).

If you want FMS to assemble the submatrix vectors, specify the number of vectors for parameter NUMVEC. If you specify 0 for NUMVEC, FMS skips opening files for the submatrix vectors.

Record Format

The record format used for the files is one of the following:

Fixed Length Record
You can create fixed length record files by specifying the record length for LENR, LENI and LENV. Use this file type if all records are approximately the same size. Note that you can use multiple files if necessary. If you do use multiple files, their file attributes must be stored together in the array LUS(25,NUMSF).
Variable Length Record
If you specify negative or zero values for LENR, LENI and LENV, FMS creates variable length record files. Use this option if you are writing a single file for wavefront numbering or your records have a variety of lengths. You can help FMS organize these files by providing an estimate of the average record length. This estimate is specified as a negative number for LENR, LENI and LENV.

Record Buffering

By default, all submatrix files are double buffered to increase the physical I/O size and overlap I/O with data generation. The FMS parameter LBUFSI controls the buffer size for the integer file LUS(2), LBUFSR controls the buffer size for the real file LUS(1) and LBUFSV controls the buffer size for the vector file LUS(8). You may use unbuffered files for fixed length record files by setting LBUFSI, LBUFSR and LBUFSV to 0 before calling FMSOS. You should only use unbuffered files if you are writing the submatrices in a random order.

Existing Files

If the FMS Parameter IEXIST is set to 0 (default), FMS will create new files. If the FMS Parameter IEXIST is set to 1, FMS will use existing files. When using existing files, the parameters LENR, LENI, LENV, NUMVEC, NUMSUB and NAME must match the existing file or a fatal error is generated.