The following examples are FORTRAN programs which illustrate how to use FMS.

There are two copies of each example. The "linked" copy has hyperlinks to all FMS subroutines and Parameters. This is useful for learning FMS.

The "code" copy has the minimum number of html tags at the beginning and end of the file. This copy is useful for extracting the code and running it on your machine.

Example 11 is designed for benchmarking. A pre-linked copy is available on this server for downloading. You may configure a problem to meet your needs and then try it on several machines.

Linked Description Code
Example_1
DESCRIPTION:
Full Incore Matrix opened by CNDANN
INPUT VALUES:
None. 		CODE
Example_2:
DESCRIPTION:
Same as Example 1 but the matrix and vector storage is dynamically allocated using the FMS memory management system.
INPUT VALUES:
  • Number of equations.
CODE
Example_3:
DESCRIPTION:
General Out-of-core Matrix populated by user-supplied subroutines.
INPUT VALUES:
  • Number of equations.
  • Number of solution vectors.
CODE
Example_4:
DESCRIPTION:
Finite Element example.
INPUT VALUES:
None. 		CODE
Example_5:
DESCRIPTION:
Finite Element example using subroutine FMSPF to eliminate equations constrained to zero.
INPUT VALUES:
None. 		CODE
Example_6:
DESCRIPTION:
Finite Element example using wavefront numbering.
INPUT VALUES:
None. 		CODE
Example_7:
DESCRIPTION:
Substructuring
INPUT VALUES:
  • Number of equations.
  • First equation of substructure (1 to N).
  • Number of solution vectors.
CODE
Example_8:
DESCRIPTION:
Full complex nonsymmetric matrix populated with FMSROW
INPUT VALUES:
None. 		CODE
Example_9:
DESCRIPTION:
Sample RCS program including using FMS utilities to fill matrix in parallel.
INPUT VALUES:
  • Number of equations.
  • Number of solution vectors.
CODE
Example_10:
DESCRIPTION:
Full Complex Symmetric Matrix populated with user-supplied subroutine CSUBLK.
INPUT VALUES:
  • Number of equations.
  • Number of solution vectors.
CODE
Example_11:
DESCRIPTION:
Benchmark problem. This example is designed for benchmarking machines

The sequence of calculations is as follows:

  • Populate and factor the matrix [A]
  • Solve [A]{X} = {B}
  • Compare {X} to the known solution.
INPUT VALUES:
  • Data type and matrix symmetry according to the following:
    • 1=Real Symmetric
    • 2=Real Nonsymmetric
    • 3=Complex Hermitian
    • 4=Complex Symmetric
    • 5=Complex Nonsymmetric
  • Number of equations
  • Number of solution vectors
  • Any FMS Parameter.
    For benchmarking you may want to review and possibly modify the following:
    • MFMAT=(1=Profile,2=Block,3=Slab)
    • MAXCPU=Number of processors to use,
    • MAXMD=Number of Real*8 words to use,
    • NOPAGE=Location of page file,
    • MDINIT=Memory initialization,
    • NEQBIO=I/O Block size
    • IALGOR=Reduced operations,
    • INCORE=(0=disk,1=memory)
    • NUMIOQ=Number of I/O queues,
    • NUMSTP=Number of stripes per queue.
  • RETURN - Ends input of FMS Parameters and continues processing.
CODE
Example_12:
DESCRIPTION:
Benchmark problem. This example is similar to Example 11, except the test data forces pivoting of almost every equation. The sequence of calculations is as follows:
  • Populate [A]
  • Factor [A]
  • Solve [A]{X} = {B}
  • Compute [F] = {X}T{Y}
  • Repopulate [A]
  • Compute {B'} = [A]{X}
  • Compute the error {B} - {B'}
INPUT VALUES:
Same as Example 11. 		CODE
Example_13:
DESCRIPTION:
This example demonstrates using the FMSPUT subroutine to write matrix and vectors terms in parallel.

The sequence of calculations is as follows:

  • Populate the vector and matrix by calling FMSPUT from subroutines which run in parallel.
  • Factor the matrix [A]
  • Solve [A]{X} = {B}
  • Compare {X} to the known solution.
INPUT VALUES:
  • Data type and matrix symmetry according to the following:
    • 1=Real Symmetric
    • 2=Real Nonsymmetric
    • 3=Complex Hermitian
    • 4=Complex Symmetric
    • 5=Complex Nonsymmetric
  • Number of equations
  • Number of solution vectors
  • Number of rows in the block used to fill the matrix
    If you enter 0, the I/O block size NEQBIO is used.
  • Number of columns in the block used to fill the matrix
    If you enter 0, the I/O block size NEQBIO is used.
  • Any FMS Parameter
  • RETURN - Ends input of FMS Parameters and continues processing.
CODE
Example_14:
DESCRIPTION:
This example shows how the FMS subroutines may be used to perform a sequence of solutions when only some of the matrix terms are changed. The original system is partitioned into the form: 
 +-    +    -+ +-  -+   +-  -+
 | A11 | A12 | | X1 |   | B1 |
 +-----+-----+ +----+ = +----+
 | A21 | A22 | | X2 |   | B2 |
 +-    +    -+ +-  -+   +-  -+

You may change any of the submatrices and only the terms needing re-evaluation are computed.

The matrix [A] is full, complex nonsymmetric and is factored with full column partial pivoting.

This Example consists of a test driver and subroutine RESOLV, which performs the work. RESOLV may be inserted into your application to perform similar analysis.

INPUT VALUES:
  • Number of equations in [A11]
  • Number of equations in [A22]
  • Number of solution vectors
  • Any FMS Parameter
  • RETURN - Ends input of FMS Parameters and continues processing.
The system is then solved the first time. When the computation is completed, you are asked the following questions:
  • Do you want another solution?
  • Do you want a new A11?
  • Do you want a new A12?
  • Do you want a new A21?
  • Do you want a new A22?
  • Do you want a new B1?
  • Do you want a new B2?
If you answer yes to any of these questions, the solution is repeated. 		CODE
Example_15:
DESCRIPTION:
This example shows how the FMS subroutine FMSMM and the FMS Parameters MMROW, MMCOL and MMKA may be used to solve a system partitioned as follows: 
 +-    +     +    -+ +-  -+   +-  -+
 | A11 | A12 | A13 | | X1 |   | B1 |
 +-----+-----+-----+ +----+   +----+
 | A21 |           | |    | = |    |
 +-----+    A22    | | X2 |   | B2 |
 | A31 |           | |    |   |    |
 +-    +-         -+ +-  -+   +-  -+
The matrix [A] is full. The symmetry may be symmetric, nonsymmetric or Hermitian. The data may be real or complex. Block format ( MFMAT=2) is used.
INPUT VALUES:
  • The FMS module number (1 to 5)
    The FMS modules are numbered as follows:
    • 1=Real Symmetric,
    • 2=Real Nonsymmetric,
    • 3=Complex Hermitian,
    • 4=Complex Symmetric,
    • 5=Complex Nonsymmetric.
  • Number of equations in [A11], N1
  • Number of columns in [A12], N2
  • Number of columns in [A13], N3
  • Number of solution vectors
  • Type of test data (1=fixed,2=random)
  • Any FMS Parameter
  • RETURN - Ends input of FMS Parameters and continues processing.
Any of the matrix size dimensions N1, N2 or N3 may be set to zero.

The system is then solved and the error computed. You are then asked,

  • Do you want another solution?
If you answer yes, the solution is repeated. 		CODE
Example_16:
DESCRIPTION:
This example shows how the FMS Parameters IREST and LOWASM may be used to restart FMS during factoring.

The sequence of calculations is as follows:

  • Populate the matrix [A]
  • Factor the matrix [A]. This process may be interrupted.
  • Solve [A]{X} = {B}
  • Compare {X} to the known solution.
This example is then run a second time to perform the following:
  • Restart factoring at the specified equation,
  • Solve [A]{X} = {B}
  • Compare {X} to the known solution.
INPUT VALUES:
Is this job being restarted?
  • For jobs NOT being restarted, the following information is supplied:
    • The FMS module number, according to the following:
      • 1=Real Symmetric
      • 2=Real Nonsymmetric
      • 3=Complex Hermitian
      • 4=Complex Symmetric
      • 5=Complex Nonsymmetric
    • Number of equations
    • Number of solution vectors
    • Any FMS Parameter.
  • For jobs being restarted, the input information is as follows:
    • Enter the highest factored equation
    • Should all files be deleted after this run?
This example uses separate files for the input and factored matrix. If you use the same file, you may need to repopulate part of the unfactored matrix data beyond the restart point. This data may have been partially overwritten by the previous factoring process. The window of potentially modified data is limited to the first segment after the restart point. 		CODE
Example_17:
DESCRIPTION:
This example shows how the FMS subroutines may be used to perform a sequence of iterative solutions. 
 +-    +    -+ +-  -+   +-  -+
 | A11 | A12 | | X1 |   | B1 |
 +-----+-----+ +----+ = +----+
 | A21 | A22 | | X2 |   | B2 |
 +-    +    -+ +-  -+   +-  -+

The system of equations is partitioned as shown above. The diagonal blocks [A11] and [A22] are factored but the off-diagonal blocks [A12] and [A21] are not. A sequence of iterative solutions is performed using Jacobi or Gauss-Seidel iteration to obtain approximate solutions {X1} and {X2}.

This approach can save computer time over the exact solution under the following conditions:

  • The matrix values in the diagonal blocks [A11] and [A22] are large compared to the values in the off-diagonal blocks [A12] and [A21].
  • An approximate solution to {X1} and {X2} is acceptable.
  • The number of vectors, times the number of iterations, is less than the dimension of [A22].
In the Jacobi solution, the "old" values of {X1} and {X2} are used to compute the new values of {X1} and {X2}. In the Gauss-Seidel solution, the old value of {X2} is first used to compute a new value of {X1}. This updated value of {X1} is then used to compute the new value of {X2}. Generally the Gauss-Seidel method will converge faster than the Jacobi method.

A variation of the Jacobi method is also presented where the solution values are the change in {DX1} and {DX2}. This approach is numerically equivalent to the standard Jacobi method that solves directly for the solution {X1} and {X2}.

After a solution is obtained, you may solve a similar problem where [A11] and [A22] may change or remain the same. It is assumed that [A12], [A21], {B1} and {B2} change.

The matrix [A] is full, complex nonsymmetric and is factored with full column partial pivoting.

This Example consists of a test driver and subroutines J_GS and JACOBI2, which performs the work. These subroutines may be inserted into your application to perform similar analysis.

INPUT VALUES:
  • Number of equations in [A11]
  • Number of equations in [A22]
  • Number of solution vectors
  • Maximum number of iterations to perform
  • Maximum solution error to terminate iterations
  • Solution method:
    • 1=Jacobi
    • 2=Gauss-Seidel
    • 3=Incremental Jacobi
  • Vector norm used to test for convergence:
    • 0=Infinity norm (maximum absolute value)
    • 1=Sum of the absolute values
    • 2=Square root of the sum of the values squared
  • If you want FMS output during the iteration
  • Any FMS Parameter
  • RETURN - Ends input of FMS Parameters and continues processing.
The system is then solved the first time. When the computation is completed, you are asked the following questions:
  • Do you want another solution?
  • Do you want a new A11?
  • Do you want a new A22?
If you answer yes to any of these questions, the solution is repeated.

When all solutions of the given problem are complete, you are asked if you want to solve another problem, in which any of the input may change.

CODE
Example_18:
DESCRIPTION:
This example illustrates how to solve with [A]T using the FMS Parameter LUTRAN.

The expression V = {C}T [Ainv] {B} is evaluated by two methods:

  1. Solve [A]{X} = {B} for {X}, then multiply Vcx = {C}T{X},
  2. Solve [A]T {Y} = {C} for {Y}, then multiply Vyb = {Y}T{B}.
The maximum error in computing [A]{X}={B} and the difference between Vcx and Vyb is computed and printed.

The calculation proceeds as follows:

  • Populate [A] with random numbers,
  • Factor [A],
  • Solve [A]{X} = {B},
  • Solve [A]T{Y} = {C},
  • Repopulate [A],
  • Compute {E} = {B} - [A]{X},
  • Compute Vcx = {C}T{X},
  • Compute Vyb = {Y}T{B},
  • Compute Ev = |Vcx - Vyb|,
  • Print the maximum value of Ei and Ev
INPUT VALUES:
Same as Example 11, except only the nonsymmetric modules RN and CN can be specified. 		CODE
Example_19:
DESCRIPTION:
This example shows how to use the user-supplied subroutines and subroutine xxDAF to read elements of a matrix file.

The calculation proceeds as follows:

  • Populate matrix [A] with test data using FMSROW,
  • Populate vector {X} with test data using FMSWRT,
  • Factor [A] into [F],
  • Solve [A]{X} = {B},
  • Read [A] and compute average values in coarse windows,
  • Read [F] and compute average values in coarse windows,
  • Check the answer
INPUT VALUES:
  • Data type and matrix symmetry according to the following:
    • 1=Real Symmetric
    • 2=Real Nonsymmetric
    • 3=Complex Hermitian
    • 4=Complex Symmetric
    • 5=Complex Nonsymmetric
  • Number of equations
  • Number of solution vectors
  • Cell size for computing averages.
    For example, if the matrix has rank 1000 and a cell size of 100 is specified, then an array of 10x10 cells will be computed and printed. Each cell will contain the average value of the 100x100 matrix elements it represents.
  • Any FMS Parameter.
 CODE
Example_20:
DESCRIPTION:
This example illustrates the use of subroutine FMSINI2 and FMS Parameter NOOPEN for estimating disk space requirements for matrix and vector files.

The calculation proceeds as follows:

  • FMS is initialized according to the input options selected,
  • Subroutine FMSIST(' NOOPEN', 1) is called to prevent files from physically being opened,
  • Subroutine RSDI, RNDI, CHDI, CSDI or CNDI is called to compute the matrix storage requirements but not physically open the file,
  • The matrix file storage requirements are computed from the matrix file attribute list LUA,
  • Subroutine FMSOV is called to compute the vector storage requirements but not physically open the file,
  • The vector file storage requirements are computed from the vector file attribute list LUX,
  • Subroutines FMSCM and FMSCV are called to close the matrix and vector files,
  • Subroutine FMSEND is called to end FMS.
INPUT VALUES:
  • Data type and matrix symmetry according to the following:
    • 1=Real Symmetric
    • 2=Real Nonsymmetric
    • 3=Complex Hermitian
    • 4=Complex Symmetric
    • 5=Complex Nonsymmetric
  • Number of equations
  • Number of solution vectors
  • Type of initialization
    • 0=Call FMSINI for a normal initialization,
    • 1=Call FMSINI2(1) for a reduced initialization,
    • 2=Call FMSINI2(2) for a reduced initialization with no output.
  • Any FMS Parameter.
 CODE
Example_21:
DESCRIPTION:
This example illustrates the use of subroutine FMSMM.

The calculation proceeds as follows:

  • Matrix or vector files [A], {A}, {A}T and {B} are filled with random numbers.
  • FMSMM is called to compute one of the following:
    • {C} = [A]{B}, Case 1
    • {C} = {A}{B}, Case 3
    • {C} = {A}T{B}, Case 4
    • [C] = {A}T{B}, Case 5
  • FMSMM is called again to compute one of the following:
    • {C} = {C} - [A]{B}, Case 1
    • {C} = {C} - {A}{B}, Case 3
    • {C} = {C} - {A}T{B}, Case 4
    • [C] = [C] - {A}T{B}, Case 5
  • [C] or {C}, which should be [0] or {0}, is checked for errors.
INPUT VALUES:
  • Data type and matrix symmetry, according to the following:
    • 1=Real Symmetric
    • 2=Real Nonsymmetric
    • 3=Complex Hermitian
    • 4=Complex Symmetric
    • 5=Complex Nonsymmetric
  • The case number, according to the following:
    • 1, {C} = {D} + s*[A]{B},
    • 3, {C} = {D} + s*{A}{B},
    • 4, {C} = {D} + s*{A}T{B},
    • 5, [C] = [D] + s*{A}T{B}
  • M, the number of rows in {C} or [C]
  • N, the number of columns in {C} (except for case 5, where N=M)
  • K, the number of rows in {B} (except for case 1, where K=M)
  • Do you want to fill (always answer Y)
  • Any FMS Parameter.
 CODE
Example_22:
DESCRIPTION:
I/O Performance Test. This example is designed to test the performance of the FMS file system.
INPUT VALUES:
  • Size of transfers (Mbytes)
  • Number of transfers
  • Any FMS Parameter.
    For testing you may want to review and possibly modify the following:
    • IOTYPE=(0=Buffered,1=Raw,2=Direct,3=Flushed)
      Set this Parameter in the license file.
    • NUMIOQ=Number of I/O queues,
    • NUMSTP=Number of stripes per queue.
    • NUMVOL=Number of volumes per stripe.
  • RETURN - Ends input of FMS Parameters and continues processing.
CODE
Example_23:
DESCRIPTION:
Mixing OpenMP and FMS parallel.
Building 2 matrices simultaneously in parallel.
INPUT VALUES:
  • Number of equations in matrix 1.
  • Number of equations in matrix 2.
  • Number of solution vectors.
  • Do you want to use OpenMP to generate the data (y,n)
    A y answer uses OpenMP directives;
    A n answer uses FMS Parallel Processing Routines
  • Do you want to use OpenMP MUTEX locks (y,n)>
    A y answer uses !$OMP CRITICAL directives
    A n answer uses FMSONE, FMSALL routines.
CODE
Example_24:
DESCRIPTION:
Finite element example using 8-node bricks.
A mesh is generated NE_THICK x NE_WIDE x NE_LONG.
The nodes are numbered first in the THICK, then in the WIDE and then in the LONG direction.
For best performance use THICK <= WIDE <= LONG.
INPUT VALUES:
  • Number of elements thick.
  • Number of elements wide.
  • Number of elements long.
  • Number of degrees of freedom per node.
 CODE