c c file hwscrt.txt (documentation for the FISHPACK solver HWSCRT) c c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . c . . c . copyright (c) 2004 by UCAR . c . . c . UNIVERSITY CORPORATION for ATMOSPHERIC RESEARCH . c . . c . all rights reserved . c . . c . . c . FISHPACK version 5.0 . c . . c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * C * * C * F I S H P A C K * C * * C * * C * A PACKAGE OF FORTRAN SUBPROGRAMS FOR THE SOLUTION OF * C * * C * SEPARABLE ELLIPTIC PARTIAL DIFFERENTIAL EQUATIONS * C * * C * (Version 5.0 , JUNE 2004) * 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 SUBROUTINE HWSCRT (A,B,M,MBDCND,BDA,BDB,C,D,N,NBDCND,BDC,BDD, C + ELMBDA,F,IDIMF,PERTRB,IERROR) C C DIMENSION OF BDA(N), BDB(N), BDC(M),BDD(M), C ARGUMENTS F(IDIMF,N) C C LATEST REVISION June 2004 C C PURPOSE SOLVES THE STANDARD FIVE-POINT FINITE C DIFFERENCE APPROXIMATION TO THE HELMHOLTZ C EQUATION IN CARTESIAN COORDINATES. THIS C EQUATION IS C C (D/DX)(DU/DX) + (D/DY)(DU/DY) C + LAMBDA*U = F(X,Y). C C USAGE CALL HWSCRT (A,B,M,MBDCND,BDA,BDB,C,D,N, C NBDCND,BDC,BDD,ELMBDA,F,IDIMF, C PERTRB,IERROR) C C ARGUMENTS C ON INPUT A,B C C THE RANGE OF X, I.E., A .LE. X .LE. B. C A MUST BE LESS THAN B. C C M C THE NUMBER OF PANELS INTO WHICH THE C INTERVAL (A,B) IS SUBDIVIDED. C HENCE, THERE WILL BE M+1 GRID POINTS C IN THE X-DIRECTION GIVEN BY C X(I) = A+(I-1)DX FOR I = 1,2,...,M+1, C WHERE DX = (B-A)/M IS THE PANEL WIDTH. C M MUST BE GREATER THAN 3. C C MBDCND C INDICATES THE TYPE OF BOUNDARY CONDITIONS C AT X = A AND X = B. C C = 0 IF THE SOLUTION IS PERIODIC IN X, C I.E., U(I,J) = U(M+I,J). C = 1 IF THE SOLUTION IS SPECIFIED AT C X = A AND X = B. C = 2 IF THE SOLUTION IS SPECIFIED AT C X = A AND THE DERIVATIVE OF THE C SOLUTION WITH RESPECT TO X IS C SPECIFIED AT X = B. C = 3 IF THE DERIVATIVE OF THE SOLUTION C WITH RESPECT TO X IS SPECIFIED AT C AT X = A AND X = B. C = 4 IF THE DERIVATIVE OF THE SOLUTION C WITH RESPECT TO X IS SPECIFIED AT C X = A AND THE SOLUTION IS SPECIFIED C AT X = B. C C BDA C A ONE-DIMENSIONAL ARRAY OF LENGTH N+1 THAT C SPECIFIES THE VALUES OF THE DERIVATIVE C OF THE SOLUTION WITH RESPECT TO X AT X = A. C C WHEN MBDCND = 3 OR 4, C C BDA(J) = (D/DX)U(A,Y(J)), J = 1,2,...,N+1. C C WHEN MBDCND HAS ANY OTHER VALUE, BDA IS C A DUMMY VARIABLE. C C BDB C A ONE-DIMENSIONAL ARRAY OF LENGTH N+1 C THAT SPECIFIES THE VALUES OF THE DERIVATIVE C OF THE SOLUTION WITH RESPECT TO X AT X = B. C C WHEN MBDCND = 2 OR 3, C C BDB(J) = (D/DX)U(B,Y(J)), J = 1,2,...,N+1 C C WHEN MBDCND HAS ANY OTHER VALUE BDB IS A C DUMMY VARIABLE. C C C,D C THE RANGE OF Y, I.E., C .LE. Y .LE. D. C C MUST BE LESS THAN D. C C N C THE NUMBER OF PANELS INTO WHICH THE C INTERVAL (C,D) IS SUBDIVIDED. HENCE, C THERE WILL BE N+1 GRID POINTS IN THE C Y-DIRECTION GIVEN BY Y(J) = C+(J-1)DY C FOR J = 1,2,...,N+1, WHERE C DY = (D-C)/N IS THE PANEL WIDTH. C N MUST BE GREATER THAN 3. C C NBDCND C INDICATES THE TYPE OF BOUNDARY CONDITIONS AT C Y = C AND Y = D. C C = 0 IF THE SOLUTION IS PERIODIC IN Y, C I.E., U(I,J) = U(I,N+J). C = 1 IF THE SOLUTION IS SPECIFIED AT C Y = C AND Y = D. C = 2 IF THE SOLUTION IS SPECIFIED AT C Y = C AND THE DERIVATIVE OF THE C SOLUTION WITH RESPECT TO Y IS C SPECIFIED AT Y = D. C = 3 IF THE DERIVATIVE OF THE SOLUTION C WITH RESPECT TO Y IS SPECIFIED AT C Y = C AND Y = D. C = 4 IF THE DERIVATIVE OF THE SOLUTION C WITH RESPECT TO Y IS SPECIFIED AT C Y = C AND THE SOLUTION IS SPECIFIED C AT Y = D. C C BDC C A ONE-DIMENSIONAL ARRAY OF LENGTH M+1 THAT C SPECIFIES THE VALUES OF THE DERIVATIVE C OF THE SOLUTION WITH RESPECT TO Y AT Y = C. C C WHEN NBDCND = 3 OR 4, C C BDC(I) = (D/DY)U(X(I),C), I = 1,2,...,M+1 C C WHEN NBDCND HAS ANY OTHER VALUE, BDC IS C A DUMMY VARIABLE. C C BDD C A ONE-DIMENSIONAL ARRAY OF LENGTH M+1 THAT C SPECIFIES THE VALUES OF THE DERIVATIVE C OF THE SOLUTION WITH RESPECT TO Y AT Y = D. C C WHEN NBDCND = 2 OR 3, C C BDD(I) = (D/DY)U(X(I),D), I = 1,2,...,M+1 C C WHEN NBDCND HAS ANY OTHER VALUE, BDD IS C A DUMMY VARIABLE. C C ELMBDA C THE CONSTANT LAMBDA IN THE HELMHOLTZ C EQUATION. IF LAMBDA .GT. 0, A SOLUTION C MAY NOT EXIST. HOWEVER, HWSCRT WILL C ATTEMPT TO FIND A SOLUTION. C C F C A TWO-DIMENSIONAL ARRAY, OF DIMENSION AT C LEAST (M+1)*(N+1), SPECIFYING VALUES OF THE C RIGHT SIDE OF THE HELMHOLTZ EQUATION AND C BOUNDARY VALUES (IF ANY). C C ON THE INTERIOR, F IS DEFINED AS FOLLOWS: C FOR I = 2,3,...,M AND J = 2,3,...,N C F(I,J) = F(X(I),Y(J)). C C ON THE BOUNDARIES, F IS DEFINED AS FOLLOWS: C FOR J=1,2,...,N+1, I=1,2,...,M+1, C C MBDCND F(1,J) F(M+1,J) C ------ --------- -------- C C 0 F(A,Y(J)) F(A,Y(J)) C 1 U(A,Y(J)) U(B,Y(J)) C 2 U(A,Y(J)) F(B,Y(J)) C 3 F(A,Y(J)) F(B,Y(J)) C 4 F(A,Y(J)) U(B,Y(J)) C C C NBDCND F(I,1) F(I,N+1) C ------ --------- -------- C C 0 F(X(I),C) F(X(I),C) C 1 U(X(I),C) U(X(I),D) C 2 U(X(I),C) F(X(I),D) C 3 F(X(I),C) F(X(I),D) C 4 F(X(I),C) U(X(I),D) C C NOTE: C IF THE TABLE CALLS FOR BOTH THE SOLUTION U C AND THE RIGHT SIDE F AT A CORNER THEN THE C SOLUTION MUST BE SPECIFIED. C C IDIMF C THE ROW (OR FIRST) DIMENSION OF THE ARRAY C F AS IT APPEARS IN THE PROGRAM CALLING C HWSCRT. THIS PARAMETER IS USED TO SPECIFY C THE VARIABLE DIMENSION OF F. IDIMF MUST C BE AT LEAST M+1 . C C C ON OUTPUT F C CONTAINS THE SOLUTION U(I,J) OF THE FINITE C DIFFERENCE APPROXIMATION FOR THE GRID POINT C (X(I),Y(J)), I = 1,2,...,M+1, C J = 1,2,...,N+1 . C C PERTRB C IF A COMBINATION OF PERIODIC OR DERIVATIVE C BOUNDARY CONDITIONS IS SPECIFIED FOR A C POISSON EQUATION (LAMBDA = 0), A SOLUTION C MAY NOT EXIST. PERTRB IS A CONSTANT, C CALCULATED AND SUBTRACTED FROM F, WHICH C ENSURES THAT A SOLUTION EXISTS. HWSCRT C THEN COMPUTES THIS SOLUTION, WHICH IS A C LEAST SQUARES SOLUTION TO THE ORIGINAL C APPROXIMATION. THIS SOLUTION PLUS ANY C CONSTANT IS ALSO A SOLUTION. HENCE, THE C SOLUTION IS NOT UNIQUE. THE VALUE OF C PERTRB SHOULD BE SMALL COMPARED TO THE C RIGHT SIDE F. OTHERWISE, A SOLUTION IS C OBTAINED TO AN ESSENTIALLY DIFFERENT C PROBLEM. THIS COMPARISON SHOULD ALWAYS C BE MADE TO INSURE THAT A MEANINGFUL C SOLUTION HAS BEEN OBTAINED. C C IERROR C AN ERROR FLAG THAT INDICATES INVALID INPUT C PARAMETERS. EXCEPT FOR NUMBERS 0 AND 6, C A SOLUTION IS NOT ATTEMPTED. C C = 0 NO ERROR C = 1 A .GE. B C = 2 MBDCND .LT. 0 OR MBDCND .GT. 4 C = 3 C .GE. D C = 4 N .LE. 3 C = 5 NBDCND .LT. 0 OR NBDCND .GT. 4 C = 6 LAMBDA .GT. 0 C = 7 IDIMF .LT. M+1 C = 8 M .LE. 3 C = 20 If the dynamic allocation of real and C complex work space required for solution C fails (for example if N,M are too large C for your computer) C C SINCE THIS IS THE ONLY MEANS OF INDICATING C A POSSIBLY INCORRECT CALL TO HWSCRT, THE C USER SHOULD TEST IERROR AFTER THE CALL. C C C SPECIAL CONDITIONS NONE C C I/O NONE C C PRECISION SINGLE C C REQUIRED files fish.f,genbun.f,gnbnaux.f,comf.f C C LANGUAGE FORTRAN 90 C C HISTORY WRITTEN BY ROLAND SWEET AT NCAR IN THE LATE C 1970'S. RELEASED ON NCAR'S PUBLIC SOFTWARE C LIBRARIES IN JANUARY 1980. c Revised in June 2004 by John Adams using c Fortran 90 dynamically allocated work space. C C PORTABILITY FORTRAN 90 C C ALGORITHM THE ROUTINE DEFINES THE FINITE DIFFERENCE C EQUATIONS, INCORPORATES BOUNDARY DATA, AND C ADJUSTS THE RIGHT SIDE OF SINGULAR SYSTEMS C AND THEN CALLS GENBUN TO SOLVE THE SYSTEM. C C TIMING FOR LARGE M AND N, THE OPERATION COUNT C IS ROUGHLY PROPORTIONAL TO C M*N*(LOG2(N) C BUT ALSO DEPENDS ON INPUT PARAMETERS NBDCND C AND MBDCND. C C ACCURACY THE SOLUTION PROCESS EMPLOYED RESULTS IN A LOSS C OF NO MORE THAN THREE SIGNIFICANT DIGITS FOR N C AND M AS LARGE AS 64. MORE DETAILS 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 REFERENCES SWARZTRAUBER,P. AND R. SWEET, "EFFICIENT C FORTRAN SUBPROGRAMS FOR THE SOLUTION OF C ELLIPTIC EQUATIONS" C NCAR TN/IA-109, JULY, 1975, 138 PP. C***********************************************************************