*DECK HWSSSP SUBROUTINE HWSSSP (TS, TF, M, MBDCND, BDTS, BDTF, PS, PF, N, + NBDCND, BDPS, BDPF, ELMBDA, F, IDIMF, PERTRB, IERROR, W) C***BEGIN PROLOGUE HWSSSP C***PURPOSE Solve a finite difference approximation to the Helmholtz C equation in spherical coordinates and on the surface of the C unit sphere (radius of 1). C***LIBRARY SLATEC (FISHPACK) C***CATEGORY I2B1A1A C***TYPE SINGLE PRECISION (HWSSSP-S) C***KEYWORDS ELLIPTIC, FISHPACK, HELMHOLTZ, PDE, SPHERICAL C***AUTHOR Adams, J., (NCAR) C Swarztrauber, P. N., (NCAR) C Sweet, R., (NCAR) C***DESCRIPTION C C Subroutine HWSSSP solves a finite difference approximation to the C Helmholtz equation in spherical coordinates and on the surface of C the unit sphere (radius of 1): C C (1/SIN(THETA))(d/dTHETA)(SIN(THETA)(dU/dTHETA)) C C + (1/SIN(THETA)**2)(d/dPHI)(dU/dPHI) C C + LAMBDA*U = F(THETA,PHI) C C Where THETA is colatitude and PHI is longitude. C C * * * * * * * * Parameter Description * * * * * * * * * * C C * * * * * * On Input * * * * * * C C TS,TF C The range of THETA (colatitude), i.e., TS .LE. THETA .LE. TF. C TS must be less than TF. TS and TF are in radians. A TS of C zero corresponds to the north pole and a TF of PI corresponds to C the south pole. C C * * * * * * * * * * * * * * IMPORTANT * * * * * * * * * * * * * * C C If TF is equal to PI then it must be computed using the statement C TF = PIMACH(DUM). This insures that TF in the users program is C equal to PI in this program which permits several tests of the C input parameters that otherwise would not be possible. C C C M C The number of panels into which the interval (TS,TF) is C subdivided. Hence, there will be M+1 grid points in the C THETA-direction given by THETA(I) = (I-1)DTHETA+TS for C I = 1,2,...,M+1, where DTHETA = (TF-TS)/M is the panel width. C M must be greater than 5. C C MBDCND C Indicates the type of boundary condition at THETA = TS and C THETA = TF. C C = 1 If the solution is specified at THETA = TS and THETA = TF. C = 2 If the solution is specified at THETA = TS and the C derivative of the solution with respect to THETA is C specified at THETA = TF (see note 2 below). C = 3 If the derivative of the solution with respect to THETA is C specified at THETA = TS and THETA = TF (see notes 1,2 C below). C = 4 If the derivative of the solution with respect to THETA is C specified at THETA = TS (see note 1 below) and the C solution is specified at THETA = TF. C = 5 If the solution is unspecified at THETA = TS = 0 and the C solution is specified at THETA = TF. C = 6 If the solution is unspecified at THETA = TS = 0 and the C derivative of the solution with respect to THETA is C specified at THETA = TF (see note 2 below). C = 7 If the solution is specified at THETA = TS and the C solution is unspecified at THETA = TF = PI. C = 8 If the derivative of the solution with respect to THETA is C specified at THETA = TS (see note 1 below) and the C solution is unspecified at THETA = TF = PI. C = 9 If the solution is unspecified at THETA = TS = 0 and C THETA = TF = PI. C C NOTES: 1. If TS = 0, do not use MBDCND = 3,4, or 8, but C instead use MBDCND = 5,6, or 9 . C 2. If TF = PI, do not use MBDCND = 2,3, or 6, but C instead use MBDCND = 7,8, or 9 . C C BDTS C A one-dimensional array of length N+1 that specifies the values C of the derivative of the solution with respect to THETA at C THETA = TS. When MBDCND = 3,4, or 8, C C BDTS(J) = (d/dTHETA)U(TS,PHI(J)), J = 1,2,...,N+1 . C C When MBDCND has any other value, BDTS is a dummy variable. C C BDTF C A one-dimensional array of length N+1 that specifies the values C of the derivative of the solution with respect to THETA at C THETA = TF. When MBDCND = 2,3, or 6, C C BDTF(J) = (d/dTHETA)U(TF,PHI(J)), J = 1,2,...,N+1 . C C When MBDCND has any other value, BDTF is a dummy variable. C C PS,PF C The range of PHI (longitude), i.e., PS .LE. PHI .LE. PF. PS C must be less than PF. PS and PF are in radians. If PS = 0 and C PF = 2*PI, periodic boundary conditions are usually prescribed. C C * * * * * * * * * * * * * * IMPORTANT * * * * * * * * * * * * * * C C If PF is equal to 2*PI then it must be computed using the C statement PF = 2.*PIMACH(DUM). This insures that PF in the users C program is equal to 2*PI in this program which permits tests of C the input parameters that otherwise would not be possible. C C C N C The number of panels into which the interval (PS,PF) is C subdivided. Hence, there will be N+1 grid points in the C PHI-direction given by PHI(J) = (J-1)DPHI+PS for C J = 1,2,...,N+1, where DPHI = (PF-PS)/N is the panel width. C N must be greater than 4. C C NBDCND C Indicates the type of boundary condition at PHI = PS and C PHI = PF. C C = 0 If the solution is periodic in PHI, i.e., C U(I,J) = U(I,N+J). C = 1 If the solution is specified at PHI = PS and PHI = PF C (see note below). C = 2 If the solution is specified at PHI = PS (see note below) C and the derivative of the solution with respect to PHI is C specified at PHI = PF. C = 3 If the derivative of the solution with respect to PHI is C specified at PHI = PS and PHI = PF. C = 4 If the derivative of the solution with respect to PHI is C specified at PS and the solution is specified at PHI = PF C (see note below). C C NOTE: NBDCND = 1,2, or 4 cannot be used with C MBDCND = 5,6,7,8, or 9 (the former indicates that the C solution is specified at a pole, the latter C indicates that the solution is unspecified). C Use instead C MBDCND = 1 or 2 . C C BDPS C A one-dimensional array of length M+1 that specifies the values C of the derivative of the solution with respect to PHI at C PHI = PS. When NBDCND = 3 or 4, C C BDPS(I) = (d/dPHI)U(THETA(I),PS), I = 1,2,...,M+1 . C C When NBDCND has any other value, BDPS is a dummy variable. C C BDPF C A one-dimensional array of length M+1 that specifies the values C of the derivative of the solution with respect to PHI at C PHI = PF. When NBDCND = 2 or 3, C C BDPF(I) = (d/dPHI)U(THETA(I),PF), I = 1,2,...,M+1 . C C When NBDCND has any other value, BDPF is a dummy variable. C C ELMBDA C The constant LAMBDA in the Helmholtz equation. If C LAMBDA .GT. 0, a solution may not exist. However, HWSSSP will C attempt to find a solution. C C F C A two-dimensional array that specifies the value of the right C side of the Helmholtz equation and boundary values (if any). C For I = 2,3,...,M and J = 2,3,...,N C C F(I,J) = F(THETA(I),PHI(J)). C C On the boundaries F is defined by C C MBDCND F(1,J) F(M+1,J) C ------ ------------ ------------ C C 1 U(TS,PHI(J)) U(TF,PHI(J)) C 2 U(TS,PHI(J)) F(TF,PHI(J)) C 3 F(TS,PHI(J)) F(TF,PHI(J)) C 4 F(TS,PHI(J)) U(TF,PHI(J)) C 5 F(0,PS) U(TF,PHI(J)) J = 1,2,...,N+1 C 6 F(0,PS) F(TF,PHI(J)) C 7 U(TS,PHI(J)) F(PI,PS) C 8 F(TS,PHI(J)) F(PI,PS) C 9 F(0,PS) F(PI,PS) C C NBDCND F(I,1) F(I,N+1) C ------ -------------- -------------- C C 0 F(THETA(I),PS) F(THETA(I),PS) C 1 U(THETA(I),PS) U(THETA(I),PF) C 2 U(THETA(I),PS) F(THETA(I),PF) I = 1,2,...,M+1 C 3 F(THETA(I),PS) F(THETA(I),PF) C 4 F(THETA(I),PS) U(THETA(I),PF) C C F must be dimensioned at least (M+1)*(N+1). C C *NOTE* C C If the table calls for both the solution U and the right side F C at a corner then the solution must be specified. C C C IDIMF C The row (or first) dimension of the array F as it appears in the C program calling HWSSSP. This parameter is used to specify the C variable dimension of F. IDIMF must be at least M+1 . C C W C A one-dimensional array that must be provided by the user for C work space. W may require up to 4*(N+1)+(16+INT(log2(N+1)))(M+1) C locations. The actual number of locations used is computed by C HWSSSP and is output in location W(1). INT( ) denotes the C FORTRAN integer function. 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),PHI(J)), C I = 1,2,...,M+1, J = 1,2,...,N+1 . C C PERTRB C If one specifies a combination of periodic, derivative or C unspecified boundary conditions for a Poisson equation C (LAMBDA = 0), a solution may not exist. PERTRB is a constant, C calculated and subtracted from F, which ensures that a solution C exists. HWSSSP then computes this solution, which is a least C squares solution to the original approximation. This solution C is not unique and is unnormalized. The value of PERTRB should C be small compared to the right side F. Otherwise , a solution C is obtained to an essentially different problem. This comparison C should always be made to insure that a meaningful solution has C been obtained. C C IERROR C An error flag that indicates invalid input parameters. Except C for numbers 0 and 8, a solution is not attempted. C C = 0 No error C = 1 TS.LT.0 or TF.GT.PI C = 2 TS.GE.TF C = 3 MBDCND.LT.1 or MBDCND.GT.9 C = 4 PS.LT.0 or PS.GT.PI+PI C = 5 PS.GE.PF C = 6 N.LT.5 C = 7 M.LT.5 C = 8 NBDCND.LT.0 or NBDCND.GT.4 C = 9 ELMBDA.GT.0 C = 10 IDIMF.LT.M+1 C = 11 NBDCND equals 1,2 or 4 and MBDCND.GE.5 C = 12 TS.EQ.0 and MBDCND equals 3,4 or 8 C = 13 TF.EQ.PI and MBDCND equals 2,3 or 6 C = 14 MBDCND equals 5,6 or 9 and TS.NE.0 C = 15 MBDCND.GE.7 and TF.NE.PI C C Since this is the only means of indicating a possibly incorrect C call to HWSSSP, the user should test IERROR after a call. C C W C Contains intermediate values that must not be destroyed if C HWSSSP will be called again with INTL = 1. W(1) contains the C required length of W . C C *Long Description: C C * * * * * * * Program Specifications * * * * * * * * * * * * C C Dimension of BDTS(N+1),BDTF(N+1),BDPS(M+1),BDPF(M+1), C Arguments F(IDIMF,N+1),W(see argument list) C C Latest January 1978 C Revision C C C Subprograms HWSSSP,HWSSS1,GENBUN,POISD2,POISN2,POISP2,COSGEN,ME C Required TRIX,TRI3,PIMACH C C Special NONE C Conditions C C Common NONE C Blocks C C I/O NONE C C Precision Single C C Specialist Paul Swarztrauber C C Language FORTRAN C C History Version 1 - September 1973 C Version 2 - April 1976 C Version 3 - January 1978 C C Algorithm The routine defines the finite difference C equations, incorporates boundary data, and adjusts C the right side of singular systems and then calls C GENBUN to solve the system. C C Space C Required CONTROL DATA 7600 C C Timing and The execution time T on the NCAR Control Data C Accuracy 7600 for subroutine HWSSSP is roughly proportional C to M*N*log2(N), but also depends on the input C parameters NBDCND and MBDCND. Some typical values C are listed in the table below. C The solution process employed results in a loss C of no more than three significant digits for N and C M as large as 64. More detailed information about C accuracy can be found in the documentation for C subroutine GENBUN which is the routine that C solves the finite difference equations. C C C M(=N) MBDCND NBDCND T(MSECS) C ----- ------ ------ -------- C C 32 0 0 31 C 32 1 1 23 C 32 3 3 36 C 64 0 0 128 C 64 1 1 96 C 64 3 3 142 C C Portability American National Standards Institute FORTRAN. C The machine dependent constant PI is defined in C function PIMACH. C C Required SIN,COS C Resident C Routines C C References P. N. Swarztrauber,'The Direct Solution Of The C Discrete Poisson Equation On The Surface Of a C Sphere, SIAM J. Numer. Anal.,15(1974), pp 212-215 C C Swarztrauber,P. and R. Sweet, 'Efficient FORTRAN C Subprograms for The Solution of Elliptic Equations' C NCAR TN/IA-109, July, 1975, 138 pp. C C * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * C C***REFERENCES P. N. Swarztrauber and R. Sweet, Efficient Fortran C subprograms for the solution of elliptic equations, C NCAR TN/IA-109, July 1975, 138 pp. C P. N. Swarztrauber, The direct solution of the discrete C Poisson equation on the surface of a sphere, SIAM C Journal on Numerical Analysis 15 (1974), pp. 212-215. C***ROUTINES CALLED HWSSS1, PIMACH C***REVISION HISTORY (YYMMDD) C 801001 DATE WRITTEN C 890531 Changed all specific intrinsics to generic. (WRB) C 891009 Removed unreferenced variable. (WRB) C 891009 REVISION DATE from Version 3.2 C 891214 Prologue converted to Version 4.0 format. (BAB) C 920501 Reformatted the REFERENCES section. (WRB) C***END PROLOGUE HWSSSP