CLAS3:  SPARSE SVD VIA LANSO (VER. 1) USING A'A COMPLEX HERMITIAN EIGENSYSTEMS

	LANSO IS A SUBROUTINE PACKAGE WRITTEN IN FORTRAN 77 DESIGNED TO FIND
	SOME EIGENVALUES AND EIGENVECTORS OF A LINEAR OPERATOR OPB THAT IS
        COMPLEX HERMITIAN.  THIS IS A MODIFIED VERSION OF THE LANSO CODE 
        DISTRIBUTED BY B. PARLETT AND HIS COLLEAGUES AT BERKELEY FOR THE REAL
        SYMMETRIC EIGENVALUE PROBLEM.  THE OPERATOR B IS
	ASSUMED TO BE OF THE FORM
  
                 B =  A'A,   WHERE A IS M BY N (M>>N), SPARSE, AND COMPLEX.
	
        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.  THE LEFT AND RIGHT
        RIGHT SINGULAR VECTORS CONTAIN ELEMENTS WITH COMPLEX VALUES WHEREAS
        THE SINGULAR VALUES ARE ALL REALS.

	LANSO IMPLEMENTS THE SIMPLE LANCZOS ALGORITHM WITH SIMON'S
	SELECTIVE ORTHOGONALIZATION TO ACTIVELY MAINTAIN EXTENDED SEMI-
	ORTHOGONALITY AMONGST THE COMPUTED (COMPLEX) LANCZOS VECTORS.

	LANSO IS MOST EFFICIENT WHEN ONLY A MODEST FRACTION (< 1/4) OF
	B-EIGENPAIRS ARE WANTED.  ONE POTENTIALLY USEFUL FEATURE OF LANSO
	IS ITS DELIVERY OF CERTAIN EIGENVALUES NOT YET GOOD TO FULL
	PRECISION, FOR SOME TASKS THEY ARE OFTEN GOOD ENOUGH.

	THE LARGEST EIGENVALUES OF B TEND TO BE CAPTURED BEFORE THE SMALL ONES
	BUT CONVERGENCE DEPENDS ON SEPARATION RATIOS AND THESE VARY WITH
	THE APPLICATION. 

        THE PROGRAM WILL FIND EIGENVALUES OF MULTIPLICITY GREATER THAN ONE
        BUT THE COPIES STABILIZE ONE AT A TIME,
        THE INTERVAL BETWEEN COPIES DEPENDS ON THE PROBLEM AND WORDLENGTH.
        EXPERIENCE SUGGESTS THE GAP IS BETWEEN 4 AND 20 STEPS.

- HOW TO USE LANSO FOR THE COMPLEX SVD PROBLEM

	ONE INVOKES LANSO THROUGH THE TOP LEVEL SUBROUTINE NAMED LANDR.

	THE CALLING SEQUENCE FOR LANDR IS
	.
	CALL LANDR(N,MAXPRS,LANMAX,ENDL,ENDR,EV,KAPPA,J,NEIG,RITZ,BND,
                   W,NW,W2,NW2,ERR,MSGLVL)
	.
	THE USER SPECIFIES AS PART OF THE PARAMETER LIST:
	.
	N		... DIMENSION OF THE EIGENPROBLEM (NCOL),
                            WHERE A IS NROW BY NCOL, AND NROW >> NCOL.
	MAXPRS		... MAXIMUM NUMBER OF EIGENPAIRS OF B WANTED,
			    (MAXPRS SHOULD BE < N/4),
	LANMAX		... MAXIMUM NUMBER OF LANCZOS STEPS ALLOWED,
			    (MAXPRS <= LANMAX <= N)
	[ENDL,ENDR]	... 2 END-POINTS OF AN INTERVAL WITHIN WHICH ALL
			    UNWANTED EIGENVALUES LIE, (ENDL < ENDR)
	                    (ONE CHOICE IS ENDL=-MACHEPS,ENDR=MACHEPS)
	EV		... {INTEGER} IF EV.LE.0 THEN ONLY EIGENVALUES AND NO
			    EIGENVECTORS ARE WANTED, OTHERWISE EV IS TAKEN
			    TO BE 3, AND THE OUTPUT FILE CLAO3 (UNFORMATTED)
                            WILL CONTAIN THE EIGENVECTORS OF B (RIGHT SINGULAR
                            VECTORS OF A) FIRST WITH THE DERIVED LEFT
                            SINGULAR VECTORS TO FOLLOW.  BOTH SETS OF SINGULAR
                            VECTORS IN CLAO3 CORRESPOND TO THE ASCENDING ORDER
                            OF THE RITZ VALUES IN THE CLAO2 OUTPUT FILE.  
	KAPPA		... {REAL*8} RELATIVE ACCURACY OF RITZ VALUES
			    ACCEPTABLE AS EIGENVALUES,
			    (KAPPA WILL BE RESET TO MAX(KAPPA,MACHEPS**(3/4))
			     IF EV.GT.0, OTHERWISE KAPPA IS UNTOUCHED)
	NW,NW2		... SIZES OF REAL AND COMPLEX WORKING ARRAYS,
			    (NW+NW2 >= 8*N+1+4*LANMAX IF EV.LE.0, OTHERWISE
			    NW+NW2 >= 8*N+1+4*LANMAX+LANMAX*LANMAX).
                            NORMALLY, NW2 SHOULD BE AT LEAST 6*N.
	W		... THE REAL-VALUED WORKING ARRAY (OF DIM. NW)
	W2		... THE COMPLEX-VALUED WORKING ARRAY (OF DIM. NW2).
	.
	THE FIRST N ENTRIES OF W2 MUST BE INITIALIZED; IF INITIALIZED
	TO ALL ZEROES, A RANDOMLY CHOSEN STARTING VECTOR WILL BE USED,
	OTHERWISE IT WILL BE TAKEN AS A USER-SPECIFIED STARTING (COMPLEX)
	VECTOR FOR THE LANCZOS RUN.
	.
	LANDR RETURNS VIA ITS PARAMETER LIST THE FOLLOWING ITEMS:
	.
	J		... NUMBER OF LANCZOS STEPS ACTUALLY TAKEN,
	NEIG		... NUMBER OF RITZ VALUES STABILIZED(SEE KAPPA),
	RITZ		... ARRAY THAT HOLDS THE (REAL) RITZ VALUES,
	BND		... ARRAY THAT HOLDS THE ERROR BOUNDS AND
	IERR		... AN ADVISORY ERROR FLAG.
	MSGLVL		... INTEGER DEBUGGING VALUE (OPTIONAL).
	.
	IF EV.GT.0 THEN
		.
		IN ADDITION, LANDR RETURNS VIA FORTRAN CHANNEL EV=3
		ALL THE EIGENVECTORS OF B WHICH CORRESPOND TO RIGHT
		(COMPLEX) SINGULAR VECTORS OF A FOLLOWED BY THE DERIVED LEFT
                (COMPLEX) SINGULAR VECTORS.  ALL THE RIGHT SINGULAR
		VECTOR ARE WRITTEN FIRST, AND THEN ALL THE LEFT SINGULAR
		VECTORS FOLLOW: ((V(K,I),K=1,NCOL,I=1,J),
		((U(K,I),K=1,NROW,I=1,J).  NOTE THAT (OUTPUT) CHANNEL
		EV=3 IS OPEN 'UNFORMATTED' TO SAVE DISK SPACE AND PRESERVE
		ACCURACY. 

	2 SUBROUTINES NAMED OPA AND OPB MUST BE SUPPLIED BY THE USER.
	.
	THE CALLING SEQUENCES ARE
	.
	CALL OPA(X,Y)
	CALL OPB(N,X,Y)
	.
	OPA TAKES A (COMPLEX) N-VECTOR X AND RETURNS Y = A*X.
        .
	OPB TAKES A (COMPLEX) N-VECTOR X AND RETURNS Y = B*X AS DESCRIBED
	ABOVE.  OPB WILL BE CALLED WITH AN N ALWAYS EQUAL TO THE
	DIMENSION OF THE EIGENPROBLEM (NCOL). IN OUR TEST PROGRAM,
        CLAS3, WE EMPLOY THE HARWELL-BOEING SPARSE MATRIX FORMAT FOR
        ACCESSING ELEMENTS OF THE NROW BY NCOL SPARSE MATRIX A AND ITS
        TRANSPOSE.  OTHER SPARSE MATRIX FORMATS CAN BE USED, OF COURSE.

	IF SECONDARY STORAGE (SUCH AS A DISK DRIVE) MUST BE USED TO
	STORE THE COMPUTED LANCZOS VECTORS, THE SUBROUTINE NAMED STORE
	MUST BE SUPPLIED BY THE USER IN PLACE OF OUR TRIVIALLY
	IMPLEMENTED STORE WHICH ASSUMES THE EXISTENCE OF VIRTUAL
	MEMORY.  THE CALLING SEQUENCE FOR STORE IS
	.
	CALL STORE(N,ISW,J,S)
	.
	WHERE
	.
	N	... THE DIMENSION OF THE EIGENPROBLEM (NCOL, FOR NROW>>NCOL),
	ISW	... ACTION TYPE SWITCH, CAN ONLY BE 1, 2, 3 OR 4.
		    ISW = 1 REQUESTS STORING OF J-TH LANCZOS VECTOR Q(J),
		    ISW = 2 REQUESTS RETRIEVAL OF J-TH LANCZOS VECTOR Q(J),
		    ISW = 3 REQUESTS STORING OF M*Q(J) FOR J = 1 OR 2,
		    ISW = 4 REQUESTS RETRIEVAL OF M*Q(J) FOR J = 1 OR 2.
	J	... INDEX OF THE J-TH LANCZOS VECTOR,
	S	... THE N-VECTOR (COMPLEX-VALUED) TO BE STORED/RETRIEVED.

	LANDR WILL END ITS RUN IF EITHER
	.
	1) MAXPRS EIGENPAIRS HAVE BEEN FOUND, OR
	2) LANMAX LANCZOS STEPS HAVE BEEN TAKEN, OR
	3) TWO RITZ VALUES INSIDE [ENDL,ENDR] HAVE STABILIZED.
	.
	WHICHEVER OCCURS FIRST.  NOTE THAT AN EIGENVALUE OF MULTIPLICITY
	HIGHER THAN ONE MAY NOT HAVE ALL ITS COPIES DELIVERED.

- ACKNOWLEDGEMENTS

	BERESFORD PARLETT AND HIS COLLEAGUES (DAVID SCOTT, HORST SIMON,
	BAHRAM NOUR-OMID, JOHN LEWIS, AND JEREMY DU CROZ) ARE TO BE CREDITED
	FOR THE ORIGINAL LANSO STRATEGY AND INITIAL FORTRAN-77 CODE.   MIN
        LIANG DID AN EXCELLENT JOB IN COVERTING THE LAS2 (REAL CASE) CODE 
        (PRODUCED BY M. BERRY) IN SVDPACK INTO CLAS3 FOR THE COMPLEX SVD
        PROBLEM.
  

- INFORMATION

        PLEASE ADDRESS ALL QUESTIONS, COMMENTS, OR CORRECTIONS TO:

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

        EMAIL: BERRY@CS.UTK.EDU

        PHONE: (423) 974-3838
        FAX:   (423) 974-4404
