NUMAL Section 3.4.1.2

BEGIN SECTION : 3.4.1.2 (February, 1979)

AUTHOR: J.J.G. ADMIRAAL.

INSTITUTE: UNIVERSITY OF AMSTERDAM.

RECEIVED: 751101.

BRIEF DESCRIPTION:

    THIS SECTION CONTAINS TWO MAIN AND NINE AUXILIARY PROCEDURES:

    THE TWO MAIN PROCEDURES ARE:
    A. QZIVAL FINDS N PAIRS OF SCALARS (ALFA[M],BETA[M]),WHERE BETA[M]
       IS REAL,SUCH THAT THE MATRIX BETA[M] * A - ALFA[M] * B IS
       SINGULAR.
    B. QZI FINDS N PAIRS OF SCALARS (ALFA[M], BETA[M]),WHERE BETA[M] IS
       REAL,SUCH THAT THE MATRIX BETA[M] * A - ALFA[M] * B IS SINGULAR;
       MOREOVER THE GENERALIZED EIGENVECTORS (THE HOMOGENOUS SOLUTION
       OF ( BETA[M] * A - ALFA[M] * B ) * X = 0 )  ARE CALCULATED.

    THE AUXILIARY PROCEDURES ARE:
    A. HSHDECMUL:
       THIS PROCEDURE CALCULATES REAL MATRICES Q AND R SUCH
       THAT Q.A=R WHERE A IS A GIVEN REAL SQUARE MATRIX, Q IS A
       PRODUCT OF HOUSEHOLDER MATRICES AND R AN UPPERTRIANGULAR MATRIX.
       MOREOVER Q.B IS FORMED WITH B, A GIVEN MATRIX.
    B. HESTGL3:
       GIVEN THE REAL SQUARE MATRICES A,B AND X, WITH B AN
       UPPER TRIANGULAR MATRIX,HESTGL3 CALCULATES THE MATRICES Q,Z,H,R,
       WHERE Q,Z ARE ORTHOGONAL, H UPPER HESSENBERG AND R AN UPPER
       TRIANGULAR MATRIX SUCH THAT Q.A.Z = H AND Q.B.Z = R.
       FURTHER: A:= Q.A.Z ; B:= Q.B.Z AND X:= Q.X.Z.
    C. HESTGL2:
       SEE HESTGL3,BUT HERE THE MATRIX X HAS BEEN LEFT OUT.
    D. HSH2COL:
       THIS PROCEDURE CALCULATES A HOUSEHOLDER MATRIX Q
       SUCH THAT BY PREMULTIPLYING A GIVEN COLUMN VECTOR V BY Q
       A ZERO ELEMENT IS FORMED IN V.
       HERE THE VECTOR V IS A COLUMN OF A MATRIX.
       FURTHER: A:= Q.A AND B:= Q.B
       WHERE A,B ARE TWO GIVEN REAL MATRICES.

    E. HSH3COL:
       THIS PROCEDURE CALCULATES A HOUSEHOLDER MATRIX
       Q SUCH THAT BY PREMULTIPLYING A GIVEN COLUMN VECTOR V BY Q TWO
       SUCCESSIVE ZERO ELEMENTS ARE FORMED IN V.
       HERE THE VECTOR V IS A COLUMN OF A MATRIX.
       FURTHER: A:= Q.A AND B:= Q.B
       WHERE A AND B ARE TWO GIVEN REAL MATRICES.
    F. HSH2ROW3:
       THIS PROCEDURE CALCULATES A HOUSEHOLDER MATRIX
       Z SUCH THAT BY POSTMULTIPLYING A GIVEN ROWVECTOR
       V BY Z A ZERO ELEMENT IS FORMED IN V.
       HERE THE VECTOR V IS A ROW OF A MATRIX.
       FURTHER: A:= A.Z; B:= B.Z AND X:= X.Z
       WHERE A,B,X ARE THREE GIVEN REAL MATRICES.
    G. HSH2ROW2:
       SEE HSH2ROW3, BUT HERE THE MATRIX X HAS BEEN LEFT OUT.
    H. HSH3ROW3:
       THIS PROCEDURE CALCULATES A HOUSEHOLDER MATRIX
       Z SUCH THAT BY POSTMULTIPLYING A GIVEN ROWVECTOR
       V BY Z, TWO SUCCESSIVE ZERO ELEMENTS ARE FORMED
       IN V. HERE THE VECTOR V IS A ROW OF A MATRIX.
       FURTHER: A:= A.Z; B:= B.Z AND X:= X.Z
       WHERE A,B AND X ARE THREE GIVEN REAL MATRICES.
    I: HSH3ROW2:
       SEE HSH3ROW3, BUT HERE THE MATRIX X HAS BEEN LEFT OUT.

KEYWORDS:
          HOUSEHOLDER'S TRANSFORMATION,
          GENERALIZED EIGENVALUES,
          GENERALIZED EIGENVECTORS,
          UPPER HESSENBERG MATRIX,
          UPPER TRIANGULAR MATRIX.

REFERENCES:

    [1]. C.B. MOLER AND G.W. STEWART.
         AN ALGORITHM FOR THE GENERALIZED MATRIX EIGENVALUE
         PROBLEM  A * X = LAMBDA * B * X.
         REPORT STANFORD UNIVERSITY
         STAN-CS-232-71;


SUBSECTION: QZIVAL

CALLING SEQUENCE:

    THE HEADING OF THE PROCEDURE IS:
    "PROCEDURE" QZIVAL(N,A,B,ALFR,ALFI,BETA,ITER,EM);
    "VALUE" N; "INTEGER" N; "ARRAY" A,B,ALFR,ALFI,BETA,EM;
    "INTEGER" "ARRAY" ITER;
    "CODE" 34600;

    THE MEANING OF THE FORMAL PARAMETERS IS:
    N:    <ARITHMETIC EXPRESSION>;
          THE NUMBER OF ROWS AND COLUMNS OF THE MATRICES A,B
    A:    <ARRAY IDENTIFIER>;
          "ARRAY" A[1:N,1:N];
          ENTRY: THE GIVEN MATRIX;
          EXIT: A QUASI UPPER-TRIANGULAR MATRIX
                (SEE METHOD AND PERFORMANCE);
    B:    <ARRAY IDENTIFIER>;
          "ARRAY" B[1:N,1:N];
          ENTRY: THE GIVEN MATRIX;
          EXIT: AN UPPER-TRIANGULAR MATRIX;
    ALFR: <ARRAY IDENTIFIER>;
          "ARRAY" ALFR[1:N];
          EXIT : THE REAL PARTS OF ALFA[1:N]
          (SEE METHOD AND PERFORMANCE);
    ALFI: <ARRAY IDENTIFIER>;
          "ARRAY" ALFI[1:N];
          EXIT : THE IMAGINARY PARTS OF ALFA[1:N];
    BETA: <ARRAY IDENTIFIER>;
          "ARRAY" BETA[1:N];
          EXIT : THE REAL SCALARS BETA[N]
    ITER: <ARRAY IDENTIFIER>;
          "INTEGER" "ARRAY" ITER[1:N];
          TROUBLE INDICATOR AND ITERATION COUNTER;
          IF ITER[1]=0 THEN NO TROUBLE IS SIGNALIZED,
          FURTHER SEE METHOD AND PERFORMANCE;
    EM:   <ARRAY IDENTIFIER>;
          "ARRAY" EM[0:1];
           ENTRY: EM[0]: THE SMALLEST POSITIVE MACHINE NUMBER;
                  EM[1]: THE RELATIVE PRECISION OF ELEMENTS OF A AND B;

PROCEDURES USED:
    TAMMAT    = CP 34014
    ELMCOL    = CP 34023
    HSHDECMUL = CP 34602
    HESTGL2   = CP 34604
    HSH2COL   = CP 34605
    HSH3COL   = CP 34606
    HSH2ROW2  = CP 34608
    HSH3ROW2  = CP 34610
    CHSH2     = CP 34611
    HSHVECMAT = CP 31070
    HSHVECTAM = CP 31073

REQUIRED CENTRAL MEMORY : HSHDECMUL DECLARES AN ARRAY OF N REALS.

RUNNING TIME: PROPORTIONAL TO N ** 3

METHOD AND PERFORMANCE;
    THE PROCEDURE QZIVAL SOLVES THE GENERALIZED MATRIX
    EIGENVALUE PROBLEM A * X = LAMBDA * B * X BY MEANS
    OF QZ ITERATION (SEE REF[1]);
    QZIVAL FINDS N PAIRS OF SCALARS (ALFA[M],BETA[M])
    SUCH THAT BETA[M] * A - ALFA[M] * B IS SINGULAR.
    THE EIGENVALUES OF A * X - LAMBDA * B * X CAN BE OBTAINED
    BY DIVIDING ALFA[M] BY BETA[M],EXCEPT BETA[M] MIGHT BE ZERO.
    IN THIS ALGORITHM ONLY UNITARY TRANSFORMATIONS ARE
    APPLIED; A FORTIORI NO INVERSES ARE CALCULATED, SO
    EITHER A OR B (OR BOTH) MAY BE SINGULAR.
    BETA[M] IS REAL, ALFA[M] IS COMPLEX.
    REAL AND IMAGINARY PARTS ARE GIVEN IN ALFR[M] AND ALFI[M].
    THE OCCURRENCE OF COMPLEX PAIRS IS ALWAYS IN
    SUCCESSIVE ELEMENTS, SUCH THAT ALFA[M]/BETA[M] AND
    ALFA[M+1]/BETA[M+1] ARE COMPLEX CONJUGATE, BUT ALFA[M]
    AND ALFA[M+1] ARE NOT NECESSARILY CONJUGATE.
    ONLY REAL ARITHMETIC IS USED IN THE PROCEDURE.
    IF A AND B WERE REDUCED TO TRIANGULAR FORM BY UNITARY
    TRANSFORMATIONS,ALFA AND BETA WOULD BE THE DIAGONALS.
    A AND B ARE ACTUALLY REDUCED TO QUASI-TRIANGULAR FORM HAVING ONLY
    1-BY-1 AND 2-BY-2 BLOCKS ON THE DIAGONAL OF A.
    IF ALFA[M] IS NOT REAL, THEN BETA[M] IS NOT ZERO.
    ITER IS THE TROUBLE INDICATOR AND ITERATION COUNTER.
    IF ITER[1]=0 THEN EVERYTHING IS O.K.
    ITER[M] IS THE NUMBER OF ITERATIONS NEEDED FOR THE M-TH EIGENVALUE.
    IF ITER[1] THROUGH ITER[M]= -1 THEN THE ITERATION FOR THE M-TH
    EIGENVALUE DID NOT CONVERGE AND ALFA[1] THROUGH ALFA[M] AND BETA[1]
    THROUGH BETA[M] ARE PROBABLY INACCURATE.

EXAMPLE OF USE:

 "BEGIN" "ARRAY" A,B[1:4,1:4],ALFR,ALFI,BETA[1:4],EM[0:1];
     "INTEGER" "ARRAY" ITER[1:4];"INTEGER" K,L;
     A[1,1]:=2; A[1,2]:=3; A[1,3]:=-3; A[1,4]:=4;

     A[2,1]:=1; A[2,2]:=-1; A[2,3]:=5; A[2,4]:=1;
     A[3,1]:=0; A[3,2]:=2; A[3,3]:=6; A[3,4]:=8;
     A[4,1]:=1; A[4,2]:=1; A[4,3]:=0; A[4,4]:=4;
     B[1,1]:=1; B[1,2]:=5; B[1,3]:=9; B[1,4]:=0;
     B[2,1]:=2; B[2,2]:=6; B[2,3]:=10; B[2,4]:=2;
     B[3,1]:=3; B[3,2]:=7; B[3,3]:=11; B[3,4]:=-1;
     B[4,1]:=4; B[4,2]:=8; B[4,3]:=12; B[4,4]:=3;
     OUTPUT(61,"(""("A")",/,4(4(+ZDBB),/),/")",A);
     OUTPUT(61,"(""("B")",/,4(4(+ZDBB),/),/")",B);
     EM[0]:=DWARF;EM[1]:="-15;
     QZIVAL(4,A,B,ALFR,ALFI,BETA,ITER,EM);
     "FOR" K:=1 "STEP" 1 "UNTIL" 4 "DO"
     OUTPUT(61,"(""("ITER[")",D,"("]=")",ZD,/")",K,ITER[K]);
     OUTPUT(61,"(""("ALFA(REAL PART)")"8B,"("ALFA(IMAGINARY PART)")"
     3B,"("BETA")",/")");
     "FOR" K:=1 "STEP" 1 "UNTIL" 4 "DO"
     OUTPUT(61,"("3(N),/")",ALFR[K],ALFI[K],BETA[K]);
     OUTPUT(61,"("/"("LAMBDA(REAL PART)")"6B,
     "("LAMBDA(IMAGINARY PART)")"/")");
     "FOR" K:=1 "STEP" 1 "UNTIL" 4 "DO"
     "BEGIN" "IF" BETA[K]=0 "THEN"
         OUTPUT(61,"(""("INFINITE")"15B,"("INDEFINITE")"/,")")
         "ELSE" OUTPUT(61,"("2(N),/")",ALFR[K]/BETA[K],ALFI[K]/BETA[K])
     "END"
 "END"

 A
  +2   +3   -3   +4
  +1   -1   +5   +1
  +0   +2   +6   +8
  +1   +1   +0   +4

 B
  +1   +5   +9   +0
  +2   +6  +10   +2
  +3   +7  +11   -1
  +4   +8  +12   +3

 ITER[1]= 0
 ITER[2]= 0
 ITER[3]= 0
 ITER[4]= 5

 ALFA(REAL PART)        ALFA(IMAGINARY PART)   BETA
 -4.4347115652167"+000  +0.0000000000000"+000  +0.0000000000000"+000
 -5.7288406521003"+000  +0.0000000000000"+000  +2.8441121744896"+000
 -8.6671777386054"-001  +2.7607904944916"+000  +8.7617886336960"+000
 -4.7262205157527"-001  -1.5054617625576"+000  +4.7778119295757"+000

 LAMBDA(REAL PART)      LAMBDA(IMAGINARY PART)
 INFINITE               INDEFINITE
 -2.0142808372628"+000  +0.0000000000000"+000
 -9.8920187429234"-002  +3.1509439566644"-001
 -9.8920187429236"-002  -3.1509439566645"-001


SUBSECTION: QZI

CALLING SEQUENCE:

    THE HEADING OF THE PROCEDURE IS:
    "PROCEDURE" QZI(N,A,B,X,ALFR,ALFI,BETA,ITER,EM);
    "VALUE" N; "INTEGER" N; "ARRAY" A,B,X,ALFR,ALFI,BETA,EM;
    "INTEGER" "ARRAY" ITER;
    "CODE" 34601;

    THE MEANING OF THE FORMAL PARAMETERS IS;
    N:    <ARITHMETIC EXPRESSION>;
          THE NUMBER OF ROWS AND COLUMNS OF THE MATRICES A,B AND X;
    A:    <ARRAY IDENTIFIER>
          "ARRAY" A[1:N,1:N];
          ENTRY: THE GIVEN MATRIX A;
          EXIT: A QUASI UPPER TRIANGULAR MATRIX;
                (SEE METHOD AND PERFORMANCE);
    B:    <ARRAY IDENTIFIER>;
          "ARRAY" B[1:N,1:N];
          ENTRY: THE GIVEN MATRIX B;
          EXIT: AN UPPER-TRIANGULAR MATRIX;
    X:    <ARRAY IDENTIFIER>;
          "ARRAY" X[1:N,1:N];
          ENTR: THE N*N UNIT MATRIX;
          EXIT: THE MATRIX OF EIGENVECTORS,
          THE EIGENVECTORS ARE STORED IN THE ARRAY X AS FOLLOWS:
          IF ALFI[M]=0 THEN X[.,M] IS THE M-TH REAL EIGENVECTOR;
          OTHERWISE, FOR EACH PAIR OF CONSECUTIVE COLUMNS
          X[.,M] AND X[.,M+1] ARE THE REAL
          AND IMAGINARY PARTS OF THE M-TH COMPLEX EIGENVECTOR.
          X[.,M] AND -X[.,M+1] ARE THE REAL AND IMAGINARY PARTS
          OF THE M+1 -ST COMPLEX EIGENVECTOR.
          THE EIGENVECTORS ARE NORMALIZED SUCH THAT THE LARGEST
          COMPONENT IS 1 OR 1 + 0 * I.
    ALFR: <ARRAY IDENTIFIER>;
          "ARRAY" ALFR[1:N];
          EXIT: THE REAL PARTS OF ALFA[1:N];
    ALFI: <ARRAY IDENTIFIER>;
          "ARRAY" ALFI[1:N];
          EXIT: THE IMAGINARY PARTS OF ALFA[1:N];
    BETA: <ARRAY IDENTIFIER>;
          "ARRAY" BETA[1:N];
    ITER: <ARRAY IDENTIFIER>;
          "INTEGER" "ARRAY" ITER[1:N];
          TROUBLE INDICATOR AND ITERATION COUNTER;
          IF ITER[1]=0 THEN NO TROUBLE IS SIGNALIZED,
          FOR FURTHER INFORMATION SEE
          METHOD AND PEFORMANCE OF PROCEDURE QZIVAL (THIS SECTION).
    EM:   <ARRAY IDENTIFIER>;
          "ARRAY" EM[0:1];
          ENTRY: EM[0]: THE SMALLEST POSITIVE MACHINE NUMBER;
                 EM[1]: THE RELATIVE PRECISION OF ELEMENTS OF A AND B;

PROCEDURES USED:

    MATMAT    = CP 34013
    TAMMAT    = CP 34014
    ELMCOL    = CP 34023
    HSHDECMUL = CP 34602
    HESTGL3   = CP 34603
    HSH2COL   = CP 34605
    HSH2ROW3  = CP 34607
    HSH3ROW3  = CP 34609
    HSH3COL   = CP 34606
    CHSH2     = CP 34611
    COMDIV    = CP 34342
    HSHVECMAT = CP 31070
    HSHVECTAM = CP 31073

RUNNING TIME: PROPORTIONAL TO N ** 3;

REQUIRED CENTRAL MEMORY : HSHDECMUL DECLARES AN ARRAY OF N REALS.

METHOD AND PERFORMANCE;

    THE PROCEDURE QZI APPLIES THE SAME METHOD AS QZIVAL.

EXAMPLE OF USE:

 "BEGIN" "ARRAY" A,B,X[1:4,1:4],ALFR,ALFI,BETA[1:4],EM[0:1];
     "INTEGER" "ARRAY" ITER[1:4];"INTEGER" K,L;
     A[1,1]:=2; A[1,2]:=3; A[1,3]:=-3; A[1,4]:=4;
     A[2,1]:=1; A[2,2]:=-1; A[2,3]:=5; A[2,4]:=1;
     A[3,1]:=0; A[3,2]:=2; A[3,3]:=6; A[3,4]:=8;
     A[4,1]:=1; A[4,2]:=1; A[4,3]:=0; A[4,4]:=4;
     B[1,1]:=1; B[1,2]:=5; B[1,3]:=9; B[1,4]:=0;
     B[2,1]:=2; B[2,2]:=6; B[2,3]:=10; B[2,4]:=2;
     B[3,1]:=3; B[3,2]:=7; B[3,3]:=11; B[3,4]:=-1;
     B[4,1]:=4; B[4,2]:=8; B[4,3]:=12; B[4,4]:=3;
     "FOR" K:=1,2,3,4 "DO" "FOR" L:=1,2,3,4 "DO"
     X[K,L]:="IF" K=L "THEN" 1 "ELSE" 0;
     OUTPUT(61,"(""("A")",/,4(4(+ZDBB),/),/")",A);
     OUTPUT(61,"(""("B")",/,4(4(+ZDBB),/),/")",B);
     EM[0]:=1.0"-280;EM[1]:="-15;
     QZI(4,A,B,X,ALFR,ALFI,BETA,ITER,EM);

     "FOR" K:=1 "STEP" 1 "UNTIL" 4 "DO"
     OUTPUT(61,"(""("ITER[")",D,"("]=")",ZD,/")",K,ITER[K]);
     OUTPUT(61,"("/"("EIGENVECTORS")",/,4(4(+D.8D"+2D2B),/),/")",X);
     OUTPUT(61,"(""("ALFA(REAL PART)")"8B,"("ALFA(IMAGINARY PART)")"
     9B,"("BETA")",/")");
     "FOR" K:=1 "STEP" 1 "UNTIL" 4 "DO"
     OUTPUT(61,"("3(N),/")",ALFR[K],ALFI[K],BETA[K]);
     OUTPUT(61,"("/"("LAMBDA(REAL PART)")"6B,
     "("LAMBDA(IMAGINARY PART)")"/")");
     "FOR" K:=1 "STEP" 1 "UNTIL" 4 "DO"
     "BEGIN" "IF" BETA[K]=0 "THEN"
         OUTPUT(61,"(""("INFINITE")"15B,"("INDEFINITE")"/")")
         "ELSE"
         OUTPUT(61,"("2(N),/")",ALFR[K]/BETA[K],ALFI[K]/BETA[K])
     "END"
 "END"

 A
  +2   +3   -3   +4
  +1   -1   +5   +1
  +0   +2   +6   +8
  +1   +1   +0   +4

 B
  +1   +5   +9   +0
  +2   +6  +10   +2
  +3   +7  +11   -1
  +4   +8  +12   +3

 ITER[1]= 0
 ITER[2]= 0
 ITER[3]= 0
 ITER[4]= 5

 EIGENVECTORS
 -5.00000000"-01  +1.00000000"+00  -6.29204867"-01  +6.52026261"-01
 +1.00000000"+00  -3.82541766"-02  +1.00000000"+00  +0.00000000"+00
 -5.00000000"-01  -3.04677732"-02  +1.65896051"-01  +1.09306265"-01
 -4.35116786"-15  -7.63328122"-01  -5.84845537"-01  +1.77430910"-01

 ALFA(REAL PART)        ALFA(IMAGINARY PART)   BETA
 -4.4347115652167"+000  +0.0000000000000"+000  +0.0000000000000"+000
 -5.7288406521003"+000  +0.0000000000000"+000  +2.8441121744896"+000
 -8.6671777386054"-001  +2.7607904944916"+000  +8.7617886336960"+000
 -4.7262205157527"-001  -1.5054617625576"+000  +4.7778119295757"+000

 LAMBDA(REAL PART)      LAMBDA(IMAGINARY PART)
 INFINITE               INDEFINITE
 -2.0142808372628"+000  +0.0000000000000"+000
 -9.8920187429234"-002  +3.1509439566644"-001
 -9.8920187429236"-002  -3.1509439566645"-001


SUBSECTION: HSHDECMUL.

CALLING SEQUENCE:

    THE HEADING OF THIS PROCEDURE IS:
    "PROCEDURE" HSHDECMUL(N,A,B,DWARF);
    "VALUE" N,DWARF; "INTEGER"N; "REAL"DWARF; "ARRAY" A,B;
    "CODE" 34602;

    THE MEANING OF THE FORMAL PARAMETERS IS:
    N: <ARITHMETIC EXPRESSION>;
       THE ORDER OF THE GIVEN MATRICES;
    A: <ARRAY IDENTIFIER>;
       "REAL" "ARRAY" A[1:N,1:N];
       ENTRY: THE GIVEN MATRIX A;
       EXIT: THE TRANSFORMED MATRIX Q.A (SEE BRIEF DESCRIPTION);
    B: <ARRAY IDENTIFIER>;
       "REAL" "ARRAY" B[1:N,1:N];
       ENTRY: THE GIVEN MATRIX B;
       EXIT: THE UPPER TRIANGULAR MATRIX Q.B (SEE BRIEF DESCRIPTION);
    DWARF: < ARITHMETIC EXPRESSION>;
       THE SMALLEST POSITIVE MACHINE NUMBER.

PROCEDURES USED:
    TAMMAT    = CP 34014;
    HSHVECMAT = CP 31070.

REQUIRED CENTRAL MEMORY : AN ARRAY OF N REALS IS DECLARED.

METHOD AND PERFORMANCE:
    FOR EACH MATRIX COLUMN A[I] A HOUSEHOLDERMATRIX Q IS FORMED,
    SUCH THAT Q.A[I] HAS ONLY ZERO ELEMENTS BELOW THE DIAGONAL ELEMENT.
    WHEN SUCCESSIVELY FOR I = 1,2,....,N-1 THESE TRANSFORMATIONS HAVE
    BEEN PERFORMED,THE MATRIX A HAS BEEN CHANGED INTO AN UPPER
    TRIANGULAR MATRIX.
    THE SAME TRANSFORMATIONS ARE PERFORMED ON THE MATRIX B

EXAMPLE OF USE:

    THE PROCEDURE HSHDECMUL IS USED IN QZI AND QZIVAL (THIS SECTION).


SUBSECTION: HESTGL3:

CALLING SEQUENCE:

    THE HEADING OF THE PROCEDURE IS:
    "PROCEDURE" HESTGL3(N,A,B,X);
    "VALUE" N; "INTEGER" N; "ARRAY" A,B,X;
    "CODE" 34603;

    THE MEANING OF THE FORMAL PARAMETERS IS:
    N: <ARITHMETIC EXPRESSION>;
       THE ORDER OF THE GIVEN MATRICES;
    A: <ARRAY IDENTIFIER>;
       "ARRAY" A[1:N,1:N];
       ENTRY: THE GIVEN MATRIX A;
       EXIT: THE UPPER HESSENBERG MATRIX Q.A.Z (SEE BRIEF DESCRIPTION);
    B: <ARRAY IDENTIFIER>;
       "ARRAY" B[1:N,1:N];
       ENTRY: THE GIVEN UPPER TRIANGULAR MATRIX B;
       EXIT: THE UPPER TRIANGULAR MATRIX Q.B.Z (SEE BRIEF DESCRIPTION);
    X: <ARRAY IDENTIFIER>;
       "ARRAY" X[1:N,1:N];
       ENTRY: THE GIVEN MATRIX X;
       EXIT: THE TRANSFORMED MATRIX Q.X.Z (SEE BRIEF DESCRIPTION);

PROCEDURES USED:
    HSH2COL  = CP 34605
    HSH2ROW3 = CP 34607

METHODE AND PERFORMANCE:
    THE REDUCTION OF THE MATRIX A TO UPPER HESSENBERG FORM
    WHILE PRESERVING THE TRIANGULARITY OF THE MATRIX B
    IS THE RESULT OF A NUMBER OF STEPS, WHICH DO THE FOLLOWING
    ACTIONS: INTRODUCING A ZERO ELEMENT IN A AND RESTORING
    THE DISTURBED ZERO IN B, WITHOUT DISTURBING THE ZERO
    INTRODUCED IN A. THIS IS DONE BY PRE-AND POSTMULTIPLICATIONS OF
    HOUSEHOLDER MATRICES.
    THE MATRIX X SHARES THE TRANSFORMATION.
    FOR FURTHER DETAILS SEE [1]

EXAMPLE OF USE:

    THE PROCEDURE HESTGL3 IS USED IN QZI (THIS SECTION).


SUBSECTION: HESTGL2:

CALLING SEQUENCE:

    THE HEADING OF THE PROCEDURE IS:
    "PROCEDURE" HESTGL2(N,A,B); "VALUE" N; "INTEGER" N; "ARRAY" A,B;
    "CODE" 34604;

    THE MEANING OF THE FORMAL PARAMETERS IS:
    N: <ARITHMETIC EXPRESSION>;
       THE ORDER OF THE GIVEN MATRICES;
    A: <ARRAY IDENTIFIER>;
       "ARRAY" A[1:N,1:N];
       ENTRY: THE GIVEN MATRIX A;
       EXIT: THE UPPER HESSENBERG MATRIX Q.A.Z (SEE BRIEF DESCRIPTION);
    B: <ARRAY IDENTIFIER>;
       "ARRAY" B[1:N,1:N];
       ENTRY: THE GIVEN UPPER TRIANGULAR MATRIX B
       EXIT: THE UPPER TRIANGULAR MATRIX Q.B.Z (SEE BRIEF DESCRIPTION);

PROCEDURES USED:
    HSH2COL  = CP 34605
    HSH2ROW2 = CP 34608

METHODE AND PERFORMANCE:
    SEE HESTGL3, BUT HERE THE MATRIX X HAS BEEN LEFT OUT.

EXAMPLE OF USE:
    THE PROCEDURE HESTGL2 IS USED IN QZIVAL (THIS SECTION).


SUBSECTION HSH2COL:

CALLING SEQUENCE:

    THE HEADING OF THE PROCEDURE IS:
    "PROCEDURE" HSH2COL(LA,LB,U,I,A1,A2,A,B); "VALUE" LA,LB,U,I,A1,A2;
    "INTEGER" LA,LB,U,I; "REAL" A1,A2; "ARRAY" A,B;
    "CODE" 34605;

    THE MEANING OF THE FORMAL PARAMETERS IS:
    LA: <ARITHMETIC EXPRESSION>;
        THE LOWER BOUND OF THE RUNNING COLUMN SUBSCRIPT OF A;
    LB: <ARITHMETIC EXPRESSION>;
        THE LOWER BOUND OF THE RUNNING COLUMN SUBSCRIPT OF B;
    U:  <ARITHMETIC EXPRESSION>;
        THE UPPER BOUND OF THE RUNNING COLUMN SUBSCRIPTS
        OF A AND B.
    I:  <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING ROW SUBSCRIPTS OF A AND B.
        I+1 IS THE UPPERBOUND.
    A1: <ARITHMETIC EXPRESSION>;
        THE I-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED.
    A2: <ARITHMETIC EXPRESSION>;
        THE (I+1)-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A:  <ARRAY IDENTIFIER>;
        "ARRAY" A[I:I+1,LA:U];
        ENTRY THE GIVEN MATRIX A;
        EXIT: THE TRANSFORMED MATRIX Q.A (SEE BRIEF DESCRIPTION);
    B:  <ARRAY IDENTIFIER>;
        "ARRAY" B[I:I+1,LB:U];
        ENTRY: THE GIVEN MATRIX B;
        EXIT: THE TRANSFORMED MATRIX Q.B (SEE BRIEF DESCRIPTION);

PROCEDURES USED:
    HSHVECMAT = CP 31070

METHOD AND PERFORMANCE:
       WHEN THE CALCULATED HOUSEHOLDER MATRIX Q PREMULTIPLIES
       A MATRIX M, ONLY ROWS I AND I+1 ARE CHANGED.
       IF THE ELEMENTS I AND I+1 IN A COLUMN OF M ARE ZERO, THEY
       REMAIN ZERO IN Q.M.
       THEREFORE ONLY THE SUBMATRICES A[I:I+1,LA:U] AND
       B[I:I+1,LB:U] ARE CHANGED, WHERE Q.A AND Q.B ARE
       OVERWRITTEN IN A RESP B.

EXAMPLE OF USE: THE PROCEDURE HSH2COL IS USED IN QZI AND QZIVAL,
                (THIS SECTION).


SUBSECTION HSH3COL:

CALLING SEQUENCE:

    THE HEADING OF THE PROCEDURE IS:
    "PROCEDURE" HSH3COL(LA,LB,U,I,A1,A2,A3,A,B);
    "VALUE" LA,LB,U,I,A1,A2,A3;"INTEGER" LA,LB,I,U;"REAL" A1,A2,A3;
    "ARRAY" A,B;
    "CODE" 34606;

    THE MEANING OF THE FORMAL PARAMETERS IS:
    LA: <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING COLUMN SUBSCRIPT OF A;
    LB: <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING COLUMN SUBSCRIPT OF B;
    U:  <ARITHMETIC EXPRESSION>;
        THE UPPERBOUND OF THE RUNNING COLUMN SUBSCRIPT OF A AND B;
    I:  <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING ROW SUBSCRIPT OF A AND B,
        I+2 IS THE UPPERBOUND;
    A1: <ARITHMETIC EXPRESSION>;
        THE I-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A2: <ARITHMETIC EXPRESSION>;
        THE (I+1)-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A3: <ARITHMETIC EXPRESSION>;
        THE (I+2)-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED.
    A:  <ARRAY IDENTIFIER>;
        "ARRAY" A[I:I+2,LA:U];
        ENTRY: THE GIVEN MATRIX A;
        EXIT: THE TRANSFORMED MATRIX Q.A (SEE BRIEF DESCRIPTION);
    B:  <ARRAY IDENTIFIER>;
        "ARRAY" B[I:I+2,LB:U];
        ENTRY: THE GIVEN MATRIX B;
        EXIT: THE TRANSFORMED MATRIX Q.B (SEE BRIEF DESCRIPTION);

PROCEDURES USED: HSHVECMAT = CP 31070;

METHOD AND PERFORMANCE:
       WHEN THE CALCULATED HOUSEHOLDER MATRIX Q PREMULTIPLIES A MATRIX
       M, ONLY ROWS I, (I+1) AND (I+2) ARE CHANGED.
       IF THE ELEMENTS I, I+1 AND I+2 ARE ZERO, THEN THEY REMAIN ZERO
       IN Q.M.
       THEREFORE ONLY THE SUBMATRICES A[I:I+2,LA:U] AND B[I:I+2,LB:U]
       ARE CHANGED, WHERE Q.A AND Q.B ARE OVERWRITTEN IN A RESP B.

EXAMPLE OF USE: THE PROCEDURE HSH3COL IS USED IN QZI AND QZIVAL
                (THIS SECTION).


SUBSECTION HSH2ROW3:

CALLING SEQUENCE:

    THE HEADING OF THE PROCEDURE IS:
    "PROCEDURE" HSH2ROW3(L,UA,UB,UX,J,A1,A2,A,B,X);
    "VALUE" L,UA,UB,UX,J,A1,A2; "INTEGER" L,UA,UB,UX,J;
    "REAL" A1,A2;"ARRAY" A,B,X;
    "CODE" 34607;

    THE MEANING OF THE FORMAL PARAMETERS IS:
    L:  <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING ROW SUBSCRIPT OF A,B AND X;
    UA: <ARITHMETIC EXPRESSION>;
        THE UPPERBOUND OF THE RUNNING ROW SUBSCRIPT OF A;
    UB: <ARITHMETIC EXPRESSION>;
        THE UPPERBOUND OF THE RUNNING ROW SUBSCRIPT OF B;
    UX: <ARITHMETIC EXPRESSION>;
        THE UPPERBOUND OF THE RUNNING ROW SUBSCRIPT OF X;
    J:  <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING COLUMN SUBSCRIPT OF A,B AND X;
        J+1 IS THE UPPERBOUND;
    A1: <ARITHMETIC EXPRESSION>;
        THE J-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A2: <ARITHMETIC EXPRESSION>;
        THE (J+1)-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A:  <ARRAY IDENTIFIER>;
        "ARRAY" A[L:UA,J:J+1];
        ENTRY: THE GIVEN MATRIX A;
        EXIT: THE TRANSFORMED MATRIX A.Z (SEE BRIEF DESCRIPTION);
    B:  <ARRAY IDENTIFIER>;
        "ARRAY" B[L:UB,J:J+1];
        ENTRY: THE GIVEN MATRIX B;
        EXIT: THE TRANSFORMED MATRIX B.Z (SEE BRIEF DESCRIPTION);
    X:  <ARRAY IDENTIFIER>;
        "ARRAY" X[L:UX,J:J+1];
        ENTRY: THE GIVEN MATRIX X;
        EXIT: THE TRANSFORMED MATRIX X.Z (SEE BRIEF DESCRIPTION);

PROCEDURES USED: HSHVECTAM = CP 31073;

METHOD AND PERFORMANCE:
    WHEN THE CALCULATED HOUSEHOLDER MATRIX Z POSTMULTIPLIES
    A MATRIX M, ONLY COLUMNS J AND J+1 ARE CHANGED.
    IF THE ELEMENTS J AND J+1 IN A ROW OF M ARE ZERO, THEN
    THEY REMAIN ZERO IN M.Z
    THEREFORE ONLY THE SUBMATRICES A[L:UA,J:J+1],B[L:UB,J:J+1]
    AND X[L:UX,J:J+1] ARE CHANGED, WHERE A.Z, B.Z AND X.Z ARE
    OVERWRITTEN IN RESP. A,B AND X.

EXAMPLE OF USE: THE PROCEDURE HSH2ROW3 IS USED IN QZI (THIS SECTION).


SUBSECTION HSH2ROW2:

CALLING SEQUENCE:

    THE HEADING OF THE PROCEDURE IS:
    "PROCEDURE" HSH2ROW2(LA,LB,UA,UB,J,A1,A2,A,B); "VALUE" LA,LB,UA,
    UB,J,A1,A2; "INTEGER" LA,LB,UA,UB,J; "REAL" A1,A2;"ARRAY" A,B;
    "CODE" 34608;

    THE MEANING OF THE FORMAL PARAMETERS IS:
    LA: <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING ROW SUBSCRIPT OF A;
    LB: <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING ROW SUBSCRIPT OF B;
    UA: <ARITHMETIC EXPRESSION>;
        THE UPPERBOUND OF THE RUNNING ROW SUBSCRIPT OF A;
    UB: <ARITHMETIC EXPRESSION>;
        THE UPPERBOUND OF THE RUNNING ROW SUBSCRIPT OF B;
    J:  <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING COLUMN SUBSCRIPT OF A AND B;
        J+1 IS THE UPPERBOUND;
    A1: < ARITHMETIC EXPRESSION>;
        THE J-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A2: <ARITHMETIC EXPRESSION>;
        THE (J+1)-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A:  <ARRAY IDENTIFIER>;
        "REAL" "ARRAY" A[LA:UA,J:J+1];
        ENTRY: THE GIVEN MATRIX A;
        EXIT: THE TRANSFORMED MATRIX A.Z (SEE BRIEF DESCRIPTION);
    B:  <ARRAY IDENTIFIER>;
        "REAL" "ARRAY" B[LB:UB,J:J+1];
        ENTRY: THE GIVEN MATRIX B;
        EXIT: THE TRANSFORMED MATRIX B.Z (SEE BRIEF DESCRIPTION);

PROCEDURES USED: HSHVECTAM = CP 31073;

METHOD AND PERFORMANCE:
    SEE HSH2ROW3, BUT HERE THE MATRIX X HAS BEEN LEFT OUT.

EXAMPLE OF USE:
        THE PROCEDURE HSH2ROW2 IS USED IN QZIVAL,
        (THIS SECTION).


SUBSECTION: HSH3ROW3.

CALLING SEQUENCE:

    THE HEADING OF THE PROCEDURE IS:
    "PROCEDURE" HSH3ROW3(L,U,UX,J,A1,A2,A3,A,B,X);
    "VALUE" L,U,UX,J,A1,A2,A3; "INTEGER" L,U,UX,J; "REAL" A1,A2,A3;
    "ARRAY" A,B,X;
    "CODE" 34609;

    THE MEANING OF THE FORMAL PARAMETERS IS:
    L:  <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING ROW SUBSCRIPT OF A AND B AND X;
    U:  <ARITHMETIC EXPRESSION>;
        THE UPPERBOUND OF THE RUNNING ROW SUBSCRIPT OF A AND B;
    UX: <ARITHMETIC EXPRESSION>;
        THE UPPERBOUND OF THE RUNNING ROW SUBSCRIPT OF X;
    J:  <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING COLUMN SUBSCRIPT OF A,B AND X;
        J+2 IS THE UPPERBOUND;
    A1: <ARITHMETIC EXPRESSION>;
        THE J-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A2: <ARITHMETIC EXPRESSION>;
        THE (J+1)-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A3: <ARITHMETIC EXPRESSION>;
        THE (J+2)-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A:  <ARRAY IDENTIFIER>;
        "REAL" "ARRAY" A[L:U,J:J+2];
        ENTRY: THE GIVEN MATRIX A;
        EXIT: THE TRANSFORMED MATRIX A.Z (SEE BRIEF DESCRIPTION);
    B:  <ARRAY IDENTIFIER>;
        "REAL" "ARRAY" B[L:U,J:J+2];
        ENTRY: THE GIVEN MATRIX B;
        EXIT: THE TRANSFORMED MATRIX B.Z (SEE BRIEF DESCRIPTION);
    X:  <ARRAY IDENTIFIER>;
        "REAL" "ARRAY" X[L:UX,J:J+2];
        ENTRY: THE GIVEN MATRIX X;
        EXIT: THE TRANSFORMED MATRIX X.Z (SEE BRIEF DESCRIPTION);

PROCEDURES USED: HSHVECTAM = CP 31073;

METHOD AND PERFORMANCE:
    WHEN THE CALCULATED HOUSEHOLDER MATRIX Z POSTMULTIPLIES A MATRIX M,
    ONLY COLUMNS J,J+1 AND J+2 ARE CHANGED.
    IF THE ELEMENTS J, J+1 AND J+2 IN A ROW OF M ARE ZERO, THEN THEY
    REMAIN ZERO IN M.Z.
    THEREFORE ONLY THE SUBMATRICES A[L:U,J:J+2], B[L:U,J:J+2] AND
    X[L:UX,J:J+2] ARE CHANGED, WHERE A.Z , B.Z AND X.Z ARE OVERWRITTEN
    ON RESP. A,B AND X;

EXAMPLE OF USE: THE PROCEDURE HSH3ROW3 IS USED IN QZI (THIS SECTION).


SUBSECTION: HSH3ROW2.

CALLING SEQUENCE:

    THE HEADING OF THE PROCEDURE IS:
    "PROCEDURE" HSH3ROW2(LA,LB,U,J,A1,A2,A3,A,B);
    "VALUE" LA,LB,U,J,A1,A2,A3; "INTEGER" LA,LB,U,J;
    "REAL" A1,A2,A3; "ARRAY" A,B;
    "CODE" 34610;

    THE MEANING OF THE FORMAL PARAMETERS IS:
    LA: <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING ROW SUBSCRIPT OF A;
    LB: <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING ROW SUBSCRIPT OF B;
    U:  <ARITHMETIC EXPRESSION>;
        THE UPPERBOUND OF THE RUNNING ROW SUBSCRIPT OF A AND B;
    J:  <ARITHMETIC EXPRESSION>;
        THE LOWERBOUND OF THE RUNNING COLUMN SUBSCRIPT OF A AND B,
        J+2 IS THE UPPERBOUND;
    A1: <ARITHMETIC EXPRESSION>;
        THE J-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A2: <ARITHMETIC EXPRESSION>;
        THE (J+1)-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A3: <ARITHMETIC EXPRESSION>;
        THE (J+2)-TH COMPONENT OF THE VECTOR TO BE TRANSFORMED;
    A:  <ARRAY IDENTIFIER>;
        "REAL" "ARRAY" A[LA:U,J:J+2];
        ENTRY: THE GIVEN MATRIX A;
        EXIT: THE TRANSFORMED MATRIX A.Z (SEE BRIEF DESCRIPTION);
    B:  <ARRAY IDENTIFIER>;
        "REAL" "ARRAY" B[LB:U,J:J+2];
        ENTRY: THE GIVEN MATRIX B;
        EXIT: THE TRANSFORMED MATRIX B.Z (SEE BRIEF DESCRIPTION);

PROCEDURES USED: HSHVECTAM = CP 31073;

METHOD AND PERFORMANCE:
       SEE HSH3ROW3, BUT HERE THE MATRIX X HAS BEEN LEFT OUT.

EXAMPLE OF USE: HSH3ROW2 IS USED IN QZIVAL (THIS SECTION).

SOURCE TEXTS:
"CODE" 34600;
"CODE" 34601;

"CODE" 34602;

"CODE" 34603;
"CODE" 34604;

"CODE" 34605;

"CODE" 34606;
"CODE" 34607;

"CODE" 34608;

"CODE" 34609;

"CODE" 34610;