c c file pois3d.txt (documentation for the FISHPACK solver POIS3D) 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 POIS3D (LPEROD,L,C1,MPEROD,M,C2,NPEROD,N,A,B,C,LDIMF, C + MDIMF,F,IERROR) C C C DIMENSION OF A(N), B(N), C(N), F(LDIMF,MDIMF,N) C ARGUMENTS C C LATEST REVISION June 2004 C C PURPOSE SOLVES THE LINEAR SYSTEM OF EQUATIONS C FOR UNKNOWN X VALUES, WHERE I=1,2,...,L, C J=1,2,...,M, AND K=1,2,...,N C C C1*(X(I-1,J,K) -2.*X(I,J,K) +X(I+1,J,K)) + C C2*(X(I,J-1,K) -2.*X(I,J,K) +X(I,J+1,K)) + C A(K)*X(I,J,K-1) +B(K)*X(I,J,K)+ C(K)*X(I,J,K+1) C = F(I,J,K) C C THE INDICES K-1 AND K+1 ARE EVALUATED MODULO N, C I.E. X(I,J,0)=X(I,J,N) AND X(I,J,N+1)=X(I,J,1). C THE UNKNOWNS C X(0,J,K), X(L+1,J,K), X(I,0,K), AND X(I,M+1,K) C ARE ASSUMED TO TAKE ON CERTAIN PRESCRIBED C VALUES DESCRIBED BELOW. C C USAGE CALL POIS3D (LPEROD,L,C1,MPEROD,M,C2,NPEROD, C N,A,B,C,LDIMF,MDIMF,F,IERROR) C C ARGUMENTS C C ON INPUT C LPEROD C INDICATES THE VALUES THAT X(0,J,K) AND C X(L+1,J,K) ARE ASSUMED TO HAVE. C = 0 X(0,J,K)=X(L,J,K), X(L+1,J,K)=X(1,J,K) C = 1 X(0,J,K) = 0, X(L+1,J,K) = 0 C = 2 X(0,J,K)=0, X(L+1,J,K)=X(L-1,J,K) C = 3 X(0,J,K)=X(2,J,K), X(L+1,J,K)=X(L-1,J,K) C = 4 X(0,J,K)=X(2,J,K), X(L+1,J,K) = 0. C C L C THE NUMBER OF UNKNOWNS IN THE I-DIRECTION. C L MUST BE AT LEAST 3. C C C1 C REAL CONSTANT IN THE ABOVE LINEAR SYSTEM C OF EQUATIONS TO BE SOLVED. C C MPEROD C INDICATES THE VALUES THAT X(I,0,K) AND C X(I,M+1,K) ARE ASSUMED TO HAVE. C = 0 X(I,0,K)=X(I,M,K), X(I,M+1,K)=X(I,1,K) C = 1 X(I,0,K)=0, X(I,M+1,K)=0 C = 2 X(I,0,K)=0, X(I,M+1,K)=X(I,M-1,K) C = 3 X(I,0,K)=X(I,2,K) X(I,M+1,K)=X(I,M-1,K) C = 4 X(I,0,K)=X(I,2,K) X(I,M+1,K)=0 C C M C THE NUMBER OF UNKNOWNS IN THE J-DIRECTION. C M MUST BE AT LEAST 3. C C C2 C REAL CONSTANT IN THE ABOVE LINEAR SYSTEM C OF EQUATIONS TO BE SOLVED. C C NPEROD C = 0 IF A(1) AND C(N) ARE NOT ZERO. C = 1 IF A(1) = C(N) = 0. C C N C THE NUMBER OF UNKNOWNS IN THE K-DIRECTION. C N MUST BE AT LEAST 3. C C A, B, C C ONE-DIMENSIONAL ARRAYS OF LENGTH N THAT C SPECIFY THE COEFFICIENTS IN THE LINEAR C EQUATIONS GIVEN ABOVE. C C IF NPEROD = 0 THE ARRAY ELEMENTS MUST NOT C DEPEND UPON INDEX K, BUT MUST BE CONSTANT. C SPECIFICALLY,THE SUBROUTINE CHECKS THE C FOLLOWING CONDITION C A(K) = C(1) C C(K) = C(1) C B(K) = B(1) C FOR K=1,2,...,N. C C LDIMF C THE ROW (OR FIRST) DIMENSION OF THE THREE- C DIMENSIONAL ARRAY F AS IT APPEARS IN THE C PROGRAM CALLING POIS3D. THIS PARAMETER IS C USED TO SPECIFY THE VARIABLE DIMENSION C OF F. LDIMF MUST BE AT LEAST L. C C MDIMF C THE COLUMN (OR SECOND) DIMENSION OF THE THREE C DIMENSIONAL ARRAY F AS IT APPEARS IN THE C PROGRAM CALLING POIS3D. THIS PARAMETER IS C USED TO SPECIFY THE VARIABLE DIMENSION C OF F. MDIMF MUST BE AT LEAST M. C C F C A THREE-DIMENSIONAL ARRAY THAT SPECIFIES THE C VALUES OF THE RIGHT SIDE OF THE LINEAR SYSTEM C OF EQUATIONS GIVEN ABOVE. F MUST BE C DIMENSIONED AT LEAST L X M X N. C C ON OUTPUT C C F C CONTAINS THE SOLUTION X. C C IERROR C AN ERROR FLAG THAT INDICATES INVALID INPUT C PARAMETERS. EXCEPT FOR NUMBER ZERO, A C SOLUTION IS NOT ATTEMPTED. C = 0 NO ERROR C = 1 IF LPEROD .LT. 0 OR .GT. 4 C = 2 IF L .LT. 3 C = 3 IF MPEROD .LT. 0 OR .GT. 4 C = 4 IF M .LT. 3 C = 5 IF NPEROD .LT. 0 OR .GT. 1 C = 6 IF N .LT. 3 C = 7 IF LDIMF .LT. L C = 8 IF MDIMF .LT. M C = 9 IF A(K) .NE. C(1) OR C(K) .NE. C(1) C OR B(I) .NE.B(1) FOR SOME K=1,2,...,N. C = 10 IF NPEROD = 1 AND A(1) .NE. 0 C OR C(N) .NE. 0 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 A C POSSIBLY INCORRECT CALL TO POIS3D, THE USER C SHOULD TEST IERROR AFTER THE CALL. C C SPECIAL CONDITIONS NONE C C I/O NONE C C PRECISION SINGLE C C REQUIRED files fish.f,comf.f,fftpack.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 THIS SUBROUTINE SOLVES THREE-DIMENSIONAL BLOCK C TRIDIAGONAL LINEAR SYSTEMS ARISING FROM FINITE C DIFFERENCE APPROXIMATIONS TO THREE-DIMENSIONAL C POISSON EQUATIONS USING THE FFT PACKAGE C FFTPACK WRITTEN BY PAUL SWARZTRAUBER. C C TIMING FOR LARGE L, M AND N, THE OPERATION COUNT C IS ROUGHLY PROPORTIONAL TO C L*M*N*(LOG2(L)+LOG2(M)+5) C BUT ALSO DEPENDS ON INPUT PARAMETERS LPEROD C AND MPEROD. C C ACCURACY TO MEASURE THE ACCURACY OF THE ALGORITHM A C UNIFORM RANDOM NUMBER GENERATOR WAS USED TO C CREATE A SOLUTION ARRAY X FOR THE SYSTEM GIVEN C IN THE 'PURPOSE' SECTION WITH C A(K) = C(K) = -0.5*B(K) = 1, K=1,2,...,N C AND, WHEN NPEROD = 1 C A(1) = C(N) = 0 C A(N) = C(1) = 2. C C THE SOLUTION X WAS SUBSTITUTED INTO THE GIVEN C SYSTEM AND, USING DOUBLE PRECISION, A RIGHT C SIDE Y WAS COMPUTED. USING THIS ARRAY Y C SUBROUTINE POIS3D WAS CALLED TO PRODUCE AN C APPROXIMATE SOLUTION Z. RELATIVE ERROR C C E = MAX(ABS(Z(I,J,K)-X(I,J,K)))/MAX(ABS(X(I,J,K C C WAS COMPUTED, WHERE THE TWO MAXIMA ARE TAKEN C OVER I=1,2,...,L, J=1,2,...,M AND K=1,2,...,N. C VALUES OF E ARE GIVEN IN THE TABLE BELOW FOR C SOME TYPICAL VALUES OF L,M AND N. C C L(=M=N) LPEROD MPEROD E C ------ ------ ------ ------ C C 16 0 0 1.E-13 C 15 1 1 4.E-13 C 17 3 3 2.E-13 C 32 0 0 2.E-13 C 31 1 1 2.E-12 C 33 3 3 7.E-13 C C REFERENCES NONE C ********************************************************************