CSISVD-3: SPARSE SVD VIA SUBSPACE ITERATION USING A'A EIGENSYSTEMS

	SISVD IS A PROGRAM WRITTEN IN FORTRAN 77 DESIGNED TO FIND SEVERAL
        OF THE LARGEST EIGENVALUES AND EIGENVECTORS OF A COMPLEX HERMITIAN
	POSITIVE DEFINITE MATRIX B.  THIS IS A MODIFIED VERSION OF THE
	RITZIT PROGRAM (ALGOL) ORIGINALLY DESIGNED BY RUTISHAUSER IN 1970
        (NUM. MATH. 16, 205-223 AND HANDBOOK FOR AUTO. COMP., VOL.II-
        LINEAR ALGEBRA, 284-302), AND RECODED IN FORTRAN BY B. GARBOW
        (ARGONNE NATIONAL LAB) IN 1976.  THE MATRIX B IS ASSUMED TO BE
        OF THE FORM
  
                 B =  A'A,   WHERE A IS M BY N (M>>N) AND SPARSE.
	
        HENCE, THE SINGULAR TRIPLETS OF A ARE COMPUTED AS THE EIGENPAIRS
        OF B.  THE EIGENVALUES OF B ARE THE SQUARES OF THE SINGULAR 
        VALUES OF A, THE EIGENVECTORS CORRESPOND TO THE RIGHT 
        SINGULAR VECTORS ONLY.  THE LEFT SINGULAR VECTORS OF A 
        ARE THEN DETERMINED BY
                          U = 1/SIGMA A*V,
        WHERE {U,SIGMA,V} IS A SINGULAR TRIPLET OF A.
        THIS PARTICULAR IMPLEMENTATION IS DISCUSSED IN "MULTIPROCESSOR
        SPARSE SVD ALGORITHMS AND APPLICATIONS", PH.D. THESIS BY M. BERRY,
        UNIVERSITY OF ILLINOIS AT URBANA-CHAMPAIGN, OCTOBER 1990.

- HOW TO USE SUBROUTINE CRITZIT FOR THE SVD (CALLED BY MAIN PROGRAM)

	THE CALLING SEQUENCE FOR CRITZIT IS
	.
        SUBROUTINE CRITZIT(NM,N,KP,KM,EPS,COPB,INF,KEM,X,D,U,W,B,F,CX,
                          RQ,S,IMEM, WORK, TAU, WORK2, NPREV)
        THE USER SPECIFIES AS PART OF THE PARAMETER LIST:
        .
        NM              ... ROW DIMENSION OF THE TWO-DIMENSIONAL ARRAY
                            PARAMETER X AS DECLARED IN MAIN PROGRAM
                            {INTEGER}.
        N               ... ORDER OF MATRIX B FOR SVD PROBLEM {INTEGER}.
                            (N MUST NOT BE GREATER THAN NM)
        KP              ... NUMBER OF SIMULTANEOUS ITERATION VECTORS
                            {INTEGER}. KP MUST NOT BE GREATER THAN N.
        KM              ... MAXIMUM NUMBER OF ITERATION STEPS TO BE
                            PERFORMED {INTEGER}.  IF STARTING VECTORS
                            FOR THE ITERATION VECTORS ARE AVAILABLE, KM
                            SHOULD BE PREFIXED WITH A MINUS SIGN.
        EPS             ... TOLERANCE FOR ACCEPTING EIGENVECTORS {EPS}.
 
        COPB            ... NAME OF THE SUBROUTINE THAT DEFINES THE MATRIX
                            B. COPB IS CALLED WITH PARAMETERS (N,U,W) AND 
                            MUST COMPUTE W=BU WITHOUT ALTERING THE VECTOR
                            U.
        INF             ... NAME OF THE SUBROUTINE THAT MAY BE USED TO OBTAIN
                            INFORMATION OR EXERT CONTROL DURING EXECUTION. 
                            INF IS CALLED WITH PARAMETERS (KS,KG,KH,F,M),
                            WHERE KS IS THE NUMBER OF THE NEXT ITERATION STEP, 
                            KG IS THE NUMBER OF ALREADY ACCEPTED EIGENVECTORS,
                            KH IS THE NUMBER OF ALREADY ACCEPTED EIGENVALUES,
                            F IS THE ARRAY OF ERROR QUANTITIES FOR THE
                            VECTORS OF X.  AN ELEMENT OF F HAS THE VALUE 4.0
                            UNTIL THE CORRESPONDING EIGENVALUE HAS BEEN 
                            ACCEPTED. M IS THE DEGREE OF THE CURRENT
                            CHEBYSHEV POLYNOMIAL.  KS,KG,KH,M ARE {INTEGER}.
                            F IS A 1-DIM. ARRAY OF LENGTH N {REAL*8}.

        KEM            ...  ADDITIONAL NUMBER OF EIGENVALUES AND 
                            CORRESPONDING EIGENVECTORS DESIRED: CRITZIT
                            WILL ATTEMPT TO FIND (KEM + NPREV) EIGENVALUES,
                            NPREV OF WHICH ARE ALREADY AVAILABLE FROM A
                            PREVIOUS RUN {INTEGER}.  (KEM MUST BE LESS 
                            THAN NPREV+KP)
                            
        X              ...  CONTAINS, IF KM IS NEGATIVE, THE STARTING VALUES
                            FOR THE ITERATION VECTORS.  OTHERWISE, ITS
                            CONTENTS ARE IGNORED AND RANDOM STARTING VALUES
                            ARE GENERATED. COLUMNS 1:NPREV OF X CONTAIN 
                            RIGHT SINGULAR VECTORS CALCULATED FROM A PREVIOUS
                            PROGRAM RUN.

         NPREV          ... NUMBER OF PREVIOUSLY CONVERGED SINGULAR
                            VALUES: THIS IS 0 FOR THE FIRST EXECUTION OF
                            CSIS3.
	.
	CRITZIT RETURNS VIA ITS PARAMETER LIST THE FOLLOWING ITEMS:
	.
        KM              ... RESET TO THE MAGNITUDE OF ITS INPUT VALUE.
 
        KEM             ... RESET TO THE NUMBER OF EIGENVALUES AND EIGENVECTORS
                            ACTUALLY ACCEPTED WITHIN THE LIMIT OF KM STEPS.

        IMEM            ... APPROXIMATE NUMBER OF BYTES NEEDED FOR THIS
                            RUN. 

        X               ... CONTAINS IN ITS FIRST (NPREV+ KEM) COLUMNS 
                            ORTHONORMAL EIGENVECTORS OF B CORRESPONDING 
                            TO THE EIGENVALUES IN ARRAY D.  THE REMAINING 
                            COLUMNS CONTAIN APPROXIMATIONS TO FURTHER 
                            EIGENVECTORS OF B (SINGULAR VECTORS OF MATRIX A). 
                            X IS A NM BY KP 2-DIM. ARRAY {COMPLEX*8}.

        D               ... CONTAINS IN ITS FIRST KEM POSITIONS THE ABSOLUTELY
                            LARGEST EIGENVALUES OF B (PERTURBED SINGULAR
                            VALUES OF A). THE REMAINING POSITIONS CONTAIN
                            APPROXIMATIONS TO SMALLER EIGENVALUES OF B
                            D IS A 1-DIM. ARRAY OF LENGTH KP {REAL*8}.
	.
	CRITZIT REQUIRES VIA ITS PARAMETER LIST THE FOLLOWING ITEMS:
	.
        U               ... TEMPORARY 1-DIM. STORAGE ARRAY OF LENGTH NM
                            {COMPLEX*8}.
        W               ... TEMPORARY 2-DIM. M BY KP STORAGE ARRAY 
                            {COMPLEX*8}.
        B               ... TEMPORARY 2-DIM. KP BY KP STORAGE ARRAY 
                            {COMPLEX*8}.
        F               ... TEMPORARY 1-DIM. STORAGE ARRAY OF LENGTH KP
                            {COMPLEX*8}.
        CX              ... TEMPORARY 1-DIM. STORAGE ARRAY OF LENGTH KP
                            {COMPLEX*8}.
        S               ... TEMPORARY 1-DIM. STORAGE ARRAY OF LENGTH KP
                            {COMPLEX*8}.
        RQ              ... TEMPORARY 1-DIM. STORAGE ARRAY OF LENGTH KP
                            {COMPLEX*8}.
        WORK            ... TEMPORARY 1-DIM STORAGE OF LENGTH 4*KP
                            {COMPLEX*8}
        TAU             ... TEMPORARY 1-DIM STORAGE OF LENGTH KP -1
                            {COMPLEX*8} 
        WORK2           ... TEMPORARY 1-DIM STORAGE OF LENGTH N
                            {REAL*4}



        .  
        SPARSE MATRIX-VECTOR MULTIPLICATION SUBROUTINES COPB AND COPA 
        MUST BE SUPPLIED BY THE USER.
	.
	THE CALLING SEQUENCE FOR COPB (WAS BRIEFLY DESCRIBED ABOVE)
	.
	CALL COPB(N,X,Y)
	.
	COPB TAKES A COMPLEX N-VECTOR X AND RETURNS THE COMPLEX N-VECTOR 
        Y = B*X.  IN OUR TEST PROGRAM, CSIS3, WE EMPLOY THE HARWELL-BOEING 
        SPARSE MATRIX FORMAT FOR ACCESSING ELEMENTS OF THE M BY N 
        SPARSE MATRIX A AND ITS CONJUGATE-TRANSPOSE.  OTHER SPARSE 
        MATRIX FORMATS CAN BE USED, OF COURSE.
	.
	THE CALLING SEQUENCE FOR COPA IS
	.
	CALL COPA(N,X,Y)
	COPA TAKES A COMPLEX N-VECTOR X AND RETURNS THE COMPLEX M-VECTOR Y=A*X.
	.
        IN ADDITION, CRITZIT REQUIRES THE FOLLOWING USER-SUPPLIED PARAMETERS
        FOR TEMPORARY ARRAY ALLOCATIONS.
        .
        USER-SUPPLIED PARAMETERS FOR CRITZIT:
        .
        NSIG            ... MAXIMUM NUMBER OF SINGULAR TRIPLETS DESIRED
                            {INTEGER}.
        VECTORS         ... ARE SINGULAR VECTORS DESIRED ON OUTPUT?
                            {BOOLEAN}.
        .
        THE MAIN PROGRAM WILL READ THE FOLLOWING PARMS FROM THE INPUT
        FILE CSII1:
        .
        NAME            ... DATASET NAME {CHAR}.
        EM              ... NUMBER OF DESIRED TRIPLETS {INTEGER}.
                            IF RSTRT IS SET TO TRUE, THEN THIS IS
                            THE NUMBER OF ADDITIONAL TRIPLETS, SINCE
                            THE PREVIOUS RUN
                            IF RSTRT IS SET TO FALSE, THEN THE FIRST
                            EM TRIPLETS ARE CALCULATED. 

        NUMEXTRA        ... ADDITIONAL VECTORS TO CARRY {INTEGER}.
        KM              ... MAXIMUM NUMBER OF ITERATIONS {INTEGER}.
        EPS             ... TOLERANCE FOR ACCEPTING SINGULAR VECTORS
                            {INTEGER}.
        VECTORS         ... OUTPUT SINGULAR VECTORS? {BOOLEAN}.
        RSTRT           ... {BOOLEAN} TRUE: USE PREVIOUSLY GENERATED
                            INFORMATION FOR SINGULAR VECTORS AND CONTROL
                            QUANTITIES. 
                            FALSE: NO SUCH INFORMATION EXISTS
        .
        THIS VERSION OF CSISVD IS DESIGNED TO APPROXIMATE THE KEM-LARGEST
        SINGULAR TRIPLETS OF A.  USERS INTERESTED IN THE KEM-SMALLEST
        SINGULAR TRIPLETS VIA SUBSPACE ITERATION SHOULD REPLACE THE
        GIVEN SUBROUTINE COPB WITH ONE THAT RETURNS Y = C*X, WHERE
        C=(ALPHA*ALPHA)*I-A'A, AND ALPHA IS ANY UPPER BOUND FOR THE LARGEST
        SINGULAR VALUE OF THE MATRIX A.
        .
        EXPLICIT CALLS TO THE UNIX TIMER "ETIME" IS MADE IN THE CSIS3 SOURCE.
        A CALL TO ANOTHER TIMING ROUTINE (ELAPSED CPU TIME) MADE BE NEEDED.
        .
        IF THE PARAMETER "VECTORS" (READ FROM CSII3) IS SET TO "TRUE",
        THE UNFORMATTED OUTPUT FILE csiov3 WILL CONTAIN THE APPROXIMATE
        SINGULAR VECTORS WRITTEN IN THE ORDER U[1], V[1], U[2], V[2],
        ..., U[KEM], V[KEM].  HERE U[I] AND V[I] DENOTE THE LEFT AND RIGHT
        SINGULAR VECTORS, RESPECTIVELY, CORRESPONDING TO THE I-TH
        APPROXIMATE SINGULAR VALUE.

	AT THE END OF PROGRAM EXECUTION, THE PROGRAM SAVES THE 
        SIZE OF CURRENT SUBSPACE, THEN NUMBER OF CONVERGED VALUES, 
        AND THE CURRENT CONTENTS OF THE WORK ARRAYS: CX(*), D(*), 
        F(*) IN THE FILE: CSIO3.PREV. THE INFORMATION IN THIS FILE
        MAY BE USED TO RESTART THE PROGRAM IN A SUCCEEDING RUN BY
        SETTING RSTRT TO TRUE.
        .
        A SAMPLE INF ROUTINE CALLED "INTROS" HAS BEEN SUPPLIED IN THE
        CSIS3 SOURCE.  THE OUTPUT FROM INTROS (CALLED BY CRITZIT) IS WRITTEN
        TO THE FORMATTED OUTPUT FILE csio.stats.
        
- SPECIFIC REFERENCES FOR SUBSPACE ITERATION AND RITZIT

        RUTISHAUSER, H., SIMULTANEOUS ITERATION METHOD FOR SYMMETRIC
        MATRICES, NUM. MATH. L6, 205-223 (1970).  (REPRINTED IN HANDBOOK
        FOR AUTOMATIC COMPUTATION, VOLUME II, LINEAR ALGEBRA, J. H.
        WILKINSON - C. REINSCH, CONTRIBUTION II/9, 284-302, SPRINGER-
        VERLAG, 1971.

        RUTISHAUSER, H., COMPUTATIONAL ASPECTS OF F. L. BAUER'S
        SIMULTANEOUS ITERATION METHOD., NUM. MATH. 13, 4-13 (1969).

        GARBOW, B. S. AND DONGARRA, J. J., PATH CHART AND DOCUMENTATION
        FOR THE EISPACK PACKAGE OF MATRIX EIGENSYSTEM ROUTINES,
        TECHNICAL MEMORANDUM NO. 250, APPLIED MATHEMATICS DIVISION,
        ARGONNE NATIONAL LABORATORY, JULY, 1974, UPDATED AUGUST, 1975.

- INFORMATION 

        PLEASE ADDRESS ALL QUESTIONS, COMMENTS, OR CORRECTIONS TO:

        M. W. BERRY
        DEPARMENT OF COMPUTER SCIENCE
        UNIVERSITY OF TENNESSEE
        107 AYRES HALL
        KNOXVILLE, TN  37996-1301

        EMAIL: BERRY@CS.UTK.EDU

        PHONE: (615) 974-5067
