SUBROUTINE HSTCSP (INTL,A,B,M,MBDCND,BDA,BDB,C,D,N,NBDCND,BDC, 1 BDD,ELMBDA,F,IDIMF,PERTRB,IERROR,W) C C C * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * C * * C * F I S H P A K * C * * C * * C * A PACKAGE OF FORTRAN SUBPROGRAMS FOR THE SOLUTION OF * C * * C * SEPARABLE ELLIPTIC PARTIAL DIFFERENTIAL EQUATIONS * C * * C * (VERSION 3.1 , OCTOBER 1980) * C * * C * BY * C * * C * JOHN ADAMS, PAUL SWARZTRAUBER AND ROLAND SWEET * C * * C * OF * C * * C * THE NATIONAL CENTER FOR ATMOSPHERIC RESEARCH * C * * C * BOULDER, COLORADO (80307) U.S.A. * C * * C * WHICH IS SPONSORED BY * C * * C * THE NATIONAL SCIENCE FOUNDATION * C * * C * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * C C C * * * * * * * * * PURPOSE * * * * * * * * * * * * * * * * * * C C HSTCSP SOLVES THE STANDARD FIVE-POINT FINITE DIFFERENCE C APPROXIMATION ON A STAGGERED GRID TO THE MODIFIED HELMHOLTZ EQUATI C SPHERICAL COORDINATES ASSUMING AXISYMMETRY (NO DEPENDENCE ON C LONGITUDE) C C (1/R**2)(D/DR)(R**2(DU/DR)) + C C 1/(R**2*SIN(THETA))(D/DTHETA)(SIN(THETA)(DU/DTHETA)) + C C (LAMBDA/(R*SIN(THETA))**2)U = F(THETA,R) C C WHERE THETA IS COLATITUDE AND R IS THE RADIAL COORDINATE. C THIS TWO-DIMENSIONAL MODIFIED HELMHOLTZ EQUATION RESULTS FROM C THE FOURIER TRANSFORM OF THE THREE-DIMENSIONAL POISSON EQUATION. C C * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * C C C * * * * * * * * PARAMETER DESCRIPTION * * * * * * * * * * C C C * * * * * * ON INPUT * * * * * * C C INTL C = 0 ON INITIAL ENTRY TO HSTCSP OR IF ANY OF THE ARGUMENTS C C, D, N, OR NBDCND ARE CHANGED FROM A PREVIOUS CALL C C = 1 IF C, D, N, AND NBDCND ARE ALL UNCHANGED FROM PREVIOUS C CALL TO HSTCSP C C NOTE: A CALL WITH INTL = 0 TAKES APPROXIMATELY 1.5 TIMES AS MUCH C TIME AS A CALL WITH INTL = 1. ONCE A CALL WITH INTL = 0 C HAS BEEN MADE THEN SUBSEQUENT SOLUTIONS CORRESPONDING TO C DIFFERENT F, BDA, BDB, BDC, AND BDD CAN BE OBTAINED C FASTER WITH INTL = 1 SINCE INITIALIZATION IS NOT REPEATED. C C A,B C THE RANGE OF THETA (COLATITUDE), I.E. A .LE. THETA .LE. B. A C MUST BE LESS THAN B AND A MUST BE NON-NEGATIVE. A AND B ARE IN C RADIANS. A = 0 CORRESPONDS TO THE NORTH POLE AND B = PI C CORRESPONDS TO THE SOUTH POLE. C C * * * IMPORTANT * * * C C IF B IS EQUAL TO PI, THEN B MUST BE COMPUTED USING THE STATEMENT C C B = PIMACH(DUM) C C THIS INSURES THAT B IN THE USER"S PROGRAM IS EQUAL TO PI IN THIS C PROGRAM WHICH PERMITS SEVERAL TESTS OF THE INPUT PARAMETERS THAT C OTHERWISE WOULD NOT BE POSSIBLE. C C * * * * * * * * * * * * C C M C THE NUMBER OF GRID POINTS IN THE INTERVAL (A,B). THE GRID POINTS C IN THE THETA-DIRECTION ARE GIVEN BY THETA(I) = A + (I-0.5)DTHETA C FOR I=1,2,...,M WHERE DTHETA =(B-A)/M. M MUST BE GREATER THAN 4. C C MBDCND C INDICATES THE TYPE OF BOUNDARY CONDITIONS AT THETA = A AND C THETA = B. C C = 1 IF THE SOLUTION IS SPECIFIED AT THETA = A AND THETA = B. C (SEE NOTES 1, 2 BELOW) C C = 2 IF THE SOLUTION IS SPECIFIED AT THETA = A AND THE DERIVATIVE C OF THE SOLUTION WITH RESPECT TO THETA IS SPECIFIED AT C THETA = B (SEE NOTES 1, 2 BELOW). C C = 3 IF THE DERIVATIVE OF THE SOLUTION WITH RESPECT TO THETA IS C SPECIFIED AT THETA = A (SEE NOTES 1, 2 BELOW) AND THETA = B. C C = 4 IF THE DERIVATIVE OF THE SOLUTION WITH RESPECT TO THETA IS C SPECIFIED AT THETA = A (SEE NOTES 1, 2 BELOW) AND THE C SOLUTION IS SPECIFIED AT THETA = B. C C = 5 IF THE SOLUTION IS UNSPECIFIED AT THETA = A = 0 AND THE C SOLUTION IS SPECIFIED AT THETA = B. (SEE NOTE 2 BELOW) C C = 6 IF THE SOLUTION IS UNSPECIFIED AT THETA = A = 0 AND THE C DERIVATIVE OF THE SOLUTION WITH RESPECT TO THETA IS C SPECIFIED AT THETA = B (SEE NOTE 2 BELOW). C C = 7 IF THE SOLUTION IS SPECIFIED AT THETA = A AND THE C SOLUTION IS UNSPECIFIED AT THETA = B = PI. C C = 8 IF THE DERIVATIVE OF THE SOLUTION WITH RESPECT TO C THETA IS SPECIFIED AT THETA = A (SEE NOTE 1 BELOW) C AND THE SOLUTION IS UNSPECIFIED AT THETA = B = PI. C C = 9 IF THE SOLUTION IS UNSPECIFIED AT THETA = A = 0 AND C THETA = B = PI. C C NOTES: 1. IF A = 0, DO NOT USE MBDCND = 1,2,3,4,7 OR 8, C BUT INSTEAD USE MBDCND = 5, 6, OR 9. C C 2. IF B = PI, DO NOT USE MBDCND = 1,2,3,4,5 OR 6, C BUT INSTEAD USE MBDCND = 7, 8, OR 9. C C WHEN A = 0 AND/OR B = PI THE ONLY MEANINGFUL BOUNDARY C CONDITION IS DU/DTHETA = 0. (SEE D. GREENSPAN, 'NUMERICAL C ANALYSIS OF ELLIPTIC BOUNDARY VALUE PROBLEMS,' HARPER AND C ROW, 1965, CHAPTER 5.) C C BDA C A ONE-DIMENSIONAL ARRAY OF LENGTH N THAT SPECIFIES THE BOUNDARY C VALUES (IF ANY) OF THE SOLUTION AT THETA = A. WHEN C MBDCND = 1, 2, OR 7, C C BDA(J) = U(A,R(J)) , J=1,2,...,N. C C WHEN MBDCND = 3, 4, OR 8, C C BDA(J) = (D/DTHETA)U(A,R(J)) , J=1,2,...,N. C C WHEN MBDCND HAS ANY OTHER VALUE, BDA IS A DUMMY VARIABLE. C C BDB C A ONE-DIMENSIONAL ARRAY OF LENGTH N THAT SPECIFIES THE BOUNDARY C VALUES OF THE SOLUTION AT THETA = B. WHEN MBDCND = 1, 4, OR 5, C C BDB(J) = U(B,R(J)) , J=1,2,...,N. C C WHEN MBDCND = 2,3, OR 6, C C BDB(J) = (D/DTHETA)U(B,R(J)) , J=1,2,...,N. C C WHEN MBDCND HAS ANY OTHER VALUE, BDB IS A DUMMY VARIABLE. C C C,D C THE RANGE OF R , I.E. C .LE. R .LE. D. C C MUST BE LESS THAN D. C MUST BE NON-NEGATIVE. C C N C THE NUMBER OF UNKNOWNS IN THE INTERVAL (C,D). THE UNKNOWNS IN C THE R-DIRECTION ARE GIVEN BY R(J) = C + (J-0.5)DR, C J=1,2,...,N, WHERE DR = (D-C)/N. N MUST BE GREATER THAN 4. C C NBDCND C INDICATES THE TYPE OF BOUNDARY CONDITIONS AT R = C C AND R = D. C C = 1 IF THE SOLUTION IS SPECIFIED AT R = C AND R = D. C C = 2 IF THE SOLUTION IS SPECIFIED AT R = C AND THE DERIVATIVE C OF THE SOLUTION WITH RESPECT TO R IS SPECIFIED AT C R = D. (SEE NOTE 1 BELOW) C C = 3 IF THE DERIVATIVE OF THE SOLUTION WITH RESPECT TO R IS C SPECIFIED AT R = C AND R = D. C C = 4 IF THE DERIVATIVE OF THE SOLUTION WITH RESPECT TO R IS C SPECIFIED AT R = C AND THE SOLUTION IS SPECIFIED AT C R = D. C C = 5 IF THE SOLUTION IS UNSPECIFIED AT R = C = 0 (SEE NOTE 2 C BELOW) AND THE SOLUTION IS SPECIFIED AT R = D. C C = 6 IF THE SOLUTION IS UNSPECIFIED AT R = C = 0 (SEE NOTE 2 C BELOW) AND THE DERIVATIVE OF THE SOLUTION WITH RESPECT TO R C IS SPECIFIED AT R = D. C C NOTE 1: IF C = 0 AND MBDCND = 3,6,8 OR 9, THE SYSTEM OF EQUATIONS C TO BE SOLVED IS SINGULAR. THE UNIQUE SOLUTION IS C DETERMINED BY EXTRAPOLATION TO THE SPECIFICATION OF C U(THETA(1),C). BUT IN THESE CASES THE RIGHT SIDE OF THE C SYSTEM WILL BE PERTURBED BY THE CONSTANT PERTRB. C C NOTE 2: NBDCND = 5 OR 6 CANNOT BE USED WITH MBDCND = 1, 2, 4, 5, C OR 7 (THE FORMER INDICATES THAT THE SOLUTION IS C UNSPECIFIED AT R = 0; THE LATTER INDICATES THAT THE C SOLUTION IS SPECIFIED). USE INSTEAD NBDCND = 1 OR 2. C C BDC C A ONE DIMENSIONAL ARRAY OF LENGTH M THAT SPECIFIES THE BOUNDARY C VALUES OF THE SOLUTION AT R = C. WHEN NBDCND = 1 OR 2, C C BDC(I) = U(THETA(I),C) , I=1,2,...,M. C C WHEN NBDCND = 3 OR 4, C C BDC(I) = (D/DR)U(THETA(I),C), I=1,2,...,M. C C WHEN NBDCND HAS ANY OTHER VALUE, BDC IS A DUMMY VARIABLE. C C BDD C A ONE-DIMENSIONAL ARRAY OF LENGTH M THAT SPECIFIES THE BOUNDARY C VALUES OF THE SOLUTION AT R = D. WHEN NBDCND = 1 OR 4, C C BDD(I) = U(THETA(I),D) , I=1,2,...,M. C C WHEN NBDCND = 2 OR 3, C C BDD(I) = (D/DR)U(THETA(I),D) , I=1,2,...,M. C C WHEN NBDCND HAS ANY OTHER VALUE, BDD IS A DUMMY VARIABLE. C C ELMBDA C THE CONSTANT LAMBDA IN THE MODIFIED HELMHOLTZ EQUATION. IF C LAMBDA IS GREATER THAN 0, A SOLUTION MAY NOT EXIST. HOWEVER, C HSTCSP WILL ATTEMPT TO FIND A SOLUTION. C C F C A TWO-DIMENSIONAL ARRAY THAT SPECIFIES THE VALUES OF THE RIGHT C SIDE OF THE MODIFIED HELMHOLTZ EQUATION. FOR I=1,2,...,M AND C J=1,2,...,N C C F(I,J) = F(THETA(I),R(J)) . C C F MUST BE DIMENSIONED AT LEAST M X N. C C IDIMF C THE ROW (OR FIRST) DIMENSION OF THE ARRAY F AS IT APPEARS IN THE C PROGRAM CALLING HSTCSP. THIS PARAMETER IS USED TO SPECIFY THE C VARIABLE DIMENSION OF F. IDIMF MUST BE AT LEAST M. C C W C A ONE-DIMENSIONAL ARRAY THAT MUST BE PROVIDED BY THE USER FOR C WORK SPACE. WITH K = INT(LOG2(N))+1 AND L = 2**(K+1), W MAY C REQUIRE UP TO (K-2)*L+K+MAX(2N,6M)+4(N+M)+5 LOCATIONS. THE C ACTUAL NUMBER OF LOCATIONS USED IS COMPUTED BY HSTCSP AND IS C RETURNED IN THE LOCATION W(1). C C C * * * * * * ON OUTPUT * * * * * * C C F C CONTAINS THE SOLUTION U(I,J) OF THE FINITE DIFFERENCE C APPROXIMATION FOR THE GRID POINT (THETA(I),R(J)) FOR C I=1,2,...,M, J=1,2,...,N. C C PERTRB C IF A COMBINATION OF PERIODIC, DERIVATIVE, OR UNSPECIFIED C BOUNDARY CONDITIONS IS SPECIFIED FOR A POISSON EQUATION C (LAMBDA = 0), A SOLUTION MAY NOT EXIST. PERTRB IS A CON- C STANT, CALCULATED AND SUBTRACTED FROM F, WHICH ENSURES C THAT A SOLUTION EXISTS. HSTCSP THEN COMPUTES THIS C SOLUTION, WHICH IS A LEAST SQUARES SOLUTION TO THE C ORIGINAL APPROXIMATION. THIS SOLUTION PLUS ANY CONSTANT IS ALSO C A SOLUTION; HENCE, THE SOLUTION IS NOT UNIQUE. THE VALUE OF C PERTRB SHOULD BE SMALL COMPARED TO THE RIGHT SIDE F. C OTHERWISE, A SOLUTION IS OBTAINED TO AN ESSENTIALLY DIFFERENT C PROBLEM. THIS COMPARISON SHOULD ALWAYS BE MADE TO INSURE THAT C A MEANINGFUL SOLUTION HAS BEEN OBTAINED. C C IERROR C AN ERROR FLAG THAT INDICATES INVALID INPUT PARAMETERS. C EXCEPT FOR NUMBERS 0 AND 10, A SOLUTION IS NOT ATTEMPTED. C C = 0 NO ERROR C C = 1 A .LT. 0 OR B .GT. PI C C = 2 A .GE. B C C = 3 MBDCND .LT. 1 OR MBDCND .GT. 9 C C = 4 C .LT. 0 C C = 5 C .GE. D C C = 6 NBDCND .LT. 1 OR NBDCND .GT. 6 C C = 7 N .LT. 5 C C = 8 NBDCND = 5 OR 6 AND MBDCND = 1, 2, 4, 5, OR 7 C C = 9 C .GT. 0 AND NBDCND .GE. 5 C C = 10 ELMBDA .GT. 0 C C = 11 IDIMF .LT. M C C = 12 M .LT. 5 C C = 13 A = 0 AND MBDCND =1,2,3,4,7 OR 8 C C = 14 B = PI AND MBDCND .LE. 6 C C = 15 A .GT. 0 AND MBDCND = 5, 6, OR 9 C C = 16 B .LT. PI AND MBDCND .GE. 7 C C = 17 LAMBDA .NE. 0 AND NBDCND .GE. 5 C C SINCE THIS IS THE ONLY MEANS OF INDICATING A POSSIBLY C INCORRECT CALL TO HSTCSP, THE USER SHOULD TEST IERROR AFTER C THE CALL. C C W C W(1) CONTAINS THE REQUIRED LENGTH OF W. ALSO W CONTAINS C INTERMEDIATE VALUES THAT MUST NOT BE DESTROYED IF HSTCSP C WILL BE CALLED AGAIN WITH INTL = 1. C C C * * * * * * * PROGRAM SPECIFICATIONS * * * * * * * * * * * * C C DIMENSION OF BDA(N),BDB(N),BDC(M),BDD(M),F(IDIMF,N), C ARGUMENTS W(SEE ARGUMENT LIST) C C LATEST JUNE 1979 C REVISION C C SUBPROGRAMS HSTCSP,HSTCS1,BLKTRI,BLKTR1,INDXA,INDXB,INDXC, C REQUIRED PROD,PRODP,CPROD,CPRODP,PPADD,PSGF,BSRH,PPSGF, C PPSPF,COMPB,TEVLS,EPMACH,STORE C C SPECIAL NONE C CONDITIONS C C COMMON CBLKT,VALU1 C BLOCKS C C I/O NONE C C PRECISION SINGLE C C SPECIALIST ROLAND SWEET C C LANGUAGE FORTRAN C C HISTORY WRITTEN BY ROLAND SWEET AT NCAR IN MAY, 1977 C C ALGORITHM THIS SUBROUTINE DEFINES THE FINITE-DIFFERENCE C EQUATIONS, INCORPORATES BOUNDARY DATA, ADJUSTS THE C RIGHT SIDE WHEN THE SYSTEM IS SINGULAR AND CALLS C BLKTRI WHICH SOLVES THE LINEAR SYSTEM OF EQUATIONS. C C SPACE 5269(DECIMAL) = 12225(OCTAL) LOCATIONS ON THE C REQUIRED NCAR CONTROL DATA 7600 C C TIMING AND THE EXECUTION TIME T ON THE NCAR CONTROL DATA C ACCURACY 7600 FOR SUBROUTINE HSTCSP IS ROUGHLY PROPORTIONAL C TO M*N*LOG2(N), BUT DEPENDS ON THE INPUT PARAMETER C INTL. SOME VALUES ARE LISTED IN THE TABLE BELOW. C THE SOLUTION PROCESS EMPLOYED RESULTS IN A LOSS C OF NO MORE THAN FOUR SIGNIFICANT DIGITS FOR N AND M C AS LARGE AS 64. MORE DETAILED INFORMATION ABOUT C ACCURACY CAN BE FOUND IN THE DOCUMENTATION FOR C SUBROUTINE BLKTRI WHICH IS THE ROUTINE THAT C ACTUALLY SOLVES THE FINITE DIFFERENCE EQUATIONS. C C C M(=N) INTL MBDCND(=NBDCND) T(MSECS) C ----- ---- --------------- -------- C C 32 0 1-6 132 C 32 1 1-6 88 C 64 0 1-6 546 C 64 1 1-6 380 C C PORTABILITY AMERICAN NATIONAL STANDARDS INSTITUTE FORTRAN. C AN APPROXIMATE MACHINE EPSILON IS COMPUTED IN C FUNCTION PIMACH. C C REQUIRED COS,SIN,CABS,CSQRT C RESIDENT C ROUTINES C C REFERENCE SWARZTRAUBER, P.N., "A DIRECT METHOD FOR THE C DISCRETE SOLUTION OF SEPARABLE ELLIPTIC EQUATIONS," C SIAM J. NUMER. ANAL. 11(1974), PP. 1136-1150. C ARBITRARY SIZE," J. COMP. PHYS. 20(1976), C PP. 171-182. C C * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * C DIMENSION F(IDIMF,1) ,BDA(1) ,BDB(1) ,BDC(1) , 1 BDD(1) ,W(1) PI = PIMACH(DUM) C C CHECK FOR INVALID INPUT PARAMETERS C IERROR = 0 IF (A.LT.0. .OR. B.GT.PI) IERROR = 1 IF (A .GE. B) IERROR = 2 IF (MBDCND.LT.1 .OR. MBDCND.GT.9) IERROR = 3 IF (C .LT. 0.) IERROR = 4 IF (C .GE. D) IERROR = 5 IF (NBDCND.LT.1 .OR. NBDCND.GT.6) IERROR = 6 IF (N .LT. 5) IERROR = 7 IF ((NBDCND.EQ.5 .OR. NBDCND.EQ.6) .AND. (MBDCND.EQ.1 .OR. 1 MBDCND.EQ.2 .OR. MBDCND.EQ.4 .OR. MBDCND.EQ.5 .OR. 2 MBDCND.EQ.7)) 3 IERROR = 8 IF (C.GT.0. .AND. NBDCND.GE.5) IERROR = 9 IF (IDIMF .LT. M) IERROR = 11 IF (M .LT. 5) IERROR = 12 IF (A.EQ.0. .AND. MBDCND.NE.5 .AND. MBDCND.NE.6 .AND. MBDCND.NE.9) 1 IERROR = 13 IF (B.EQ.PI .AND. MBDCND.LE.6) IERROR = 14 IF (A.GT.0. .AND. (MBDCND.EQ.5 .OR. MBDCND.EQ.6 .OR. MBDCND.EQ.9)) 1 IERROR = 15 IF (B.LT.PI .AND. MBDCND.GE.7) IERROR = 16 IF (ELMBDA.NE.0. .AND. NBDCND.GE.5) IERROR = 17 IF (IERROR .NE. 0) GO TO 101 IWBM = M+1 IWCM = IWBM+M IWAN = IWCM+M IWBN = IWAN+N IWCN = IWBN+N IWSNTH = IWCN+N IWRSQ = IWSNTH+M IWWRK = IWRSQ+N IERR1 = 0 CALL HSTCS1 (INTL,A,B,M,MBDCND,BDA,BDB,C,D,N,NBDCND,BDC,BDD, 1 ELMBDA,F,IDIMF,PERTRB,IERR1,W,W(IWBM),W(IWCM), 2 W(IWAN),W(IWBN),W(IWCN),W(IWSNTH),W(IWRSQ),W(IWWRK)) W(1) = W(IWWRK)+FLOAT(IWWRK-1) IERROR = IERR1 101 CONTINUE RETURN END .