
      This collection contains at present (13 September 1993)
      4 implementations of the mixed block elimination method
      BEMW of W. Govaerts and J. D. Pryce, contained in the
      files

          SBEMW.FOR
          DBEMW.FOR
          CBEMW.FOR
          SSBEMW.FOR

      respectively for

          single precision real matrices (recognizable by first 
                 letter S in the names of the routines)
          double precision real matrices (recognizable by first
                 letter D in the names of the routines)
          single precision complex matrices (recognizable by
                 first letter C in the names of the routines)
          single precision real symmetric matrices (recognizable
                 by first letters SS in the names of the
                 routines)

      It further contains two testfiles

          STEST.FOR
          STEST1.FOR

      and this README file.
 
      Background: 
      ----------- 


      The problem under consideration is always that of a linear
      system of the form

                 M Z = H

      where M is a bordered extension of A, i.e. M has the block
      form
 
                    ( A     B )
                 M =(         )  
                    ( C^T   D ) 
    
      and that of a linear system with the transposed matrix M^T
      (no transpose in the symmetric case). Here 

      A is a square matrix of order n x n such that solvers
      for both A and A^T (=Atranspose) are given (in the symmetric 
      case A must be symmetric and only one solver is required). 
      ONLY THESE SOLVERS ARE USED IN THE CODE, A IS NEVER
      REFERRED TO.

      B , C , D are n x m, n x m and m x m respectively.
      In the symmetric case C=B and D must be symmetric.

      Z and H ARE (n + m) - dimensional column vectors.

      The typical application is when m << n and solvers for A 
      and A^T are available and exploit special properties
      of A (band structure, symmetry, sparsity, ...). One
      wants to use these solvers to solve linear systems
      with M. The proposed algorithms do this in a backward
      stable way if the solvers for A and A^T are themselves
      backward stable. In particular, if M is a well -
      conditioned matrix, then the algorithms solve
      linear systems with M accurately, even if A is
      ill - conditioned and the results obtained by
      applying the solvers for A and A^T are correspondingly
      inaccurate (for theory as well as a history of the
      problem, see the references). 

      In each case there is a preprocessing (factorization)
      stage in which only M is treated and a solution stage
      in which Z is involved as well. In the cases 
      S, D and C the preprocessing stage requires m solves with
      A and m solves with A^T. The solution stage requires
      1 solve with A for each right hand side with M and
      1 solve with A^T for each right hand side with M^T.
      In the symmetric case the preprocessing stage
      simplifies and only m solves with A are needed.

      Extensive numerical tests are described in [1,2]. A typical
      application in a dynamical systems context is described
      in [3].

      Contents of the files:
      ----------------------

      For each case there is a file that contains a driver
      program and all necessary subroutines. These files 
      are respectively called
 
               SBEMW.FOR
               DBEMW.FOR
               CBEMW.FOR
               SSBEMW.FOR

      Each file starts with a driver program that treats a
      very simple example with N=2, M=2. The driver programs
      are called

               SBEDR
               DBEDR
               CBEDR
               SSBEDR

      respectively. These driver programs contain general
      instructions on the use of the programs and can themselves
      be used as templates for applications.

      The driver programs are written in reverse communication
      mode, i.e. their subroutines return control to the
      driving program when linear systems with A or A^T are
      to be solved. This allows the user to call the solvers
      only from the main program and not from subroutines.

      Each of these files further contains four core BEMW
      subroutines, called XBEMSO, XBEMFA, XBEM1, XBEM2 
      with X = S, D, C in the first tree cases and called
      SSBEMS, SSBEMF, SSBEM1, SSBEM2  in the fourth case.

      Each file further contains the solver subroutines.
      In the first three cases, the solvers for A and A^T
      are called XSA and XSASTA respectively, where X =
      S, D, C. In the fourth case only a solver for A is
      needed; it is called SSSA.

      Each file also contains three BLAS subroutines.

      The files STEST.FOR and STEST1.FOR contain test 
      programs for the S - version of BEMW. 
      They test the behaviour of the
      algorithm in cases where A tends to singularity.
      In STEST.FOR the situation has the additional
      complication that the 1-bordered extension of
      A (obtained by deleting the last row and last
      column of M) is also singular. In STEST1.FOR
      this 1-bordered extension is nonsingular.
      The output of these test programs shows how
      pathological cases are detected by the
      error reporting variable IREP.
      The programs STEST.FOR and STEST1.FOR can
      of course be adapted to the D, C and SS cases.
      Descriptions of other tests, in particular for
      bigger matrices, are given in the references.
        
      References:
      -----------

      1. W. Govaerts, Stable solvers and block elimination for
      bordered systems, SIAM J. Matr. Anal. Appl. 
      12 (1991) 469-483 
      2. W. Govaerts and J.D. Pryce, Mixed block elimination for
      linear systems with wider borders, IMA J. Num. Anal.
      13 (1993) 161-180.
      3. W. Govaerts, Solution of bordered singular systems in
      numerical continuation and bifurcation, to appear in
      J. Comp. Appl. Maths.

      
