c c file poistg.txt (documentation for the FISHPACK solver POISTG) 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 POISTG (NPEROD,N,MPEROD,M,A,B,C,IDIMY,Y,IERROR) C C C DIMENSION OF A(M), B(M), C(M), Y(IDIMY,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,...,M C AND J=1,2,...,N C C A(I)*X(I-1,J) + B(I)*X(I,J) + C(I)*X(I+1,J) C + X(I,J-1) - 2.*X(I,J) + X(I,J+1) C = Y(I,J) C C THE INDICES I+1 AND I-1 ARE EVALUATED MODULO M, C I.E. X(0,J) = X(M,J) AND X(M+1,J) = X(1,J), AND C X(I,0) MAY BE EQUAL TO X(I,1) OR -X(I,1), AND C X(I,N+1) MAY BE EQUAL TO X(I,N) OR -X(I,N), C DEPENDING ON AN INPUT PARAMETER. C C USAGE CALL POISTG (NPEROD,N,MPEROD,M,A,B,C,IDIMY,Y, C IERROR) C C ARGUMENTS C C ON INPUT C C NPEROD C INDICATES VALUES WHICH X(I,0) AND X(I,N+1) C ARE ASSUMED TO HAVE. C = 1 IF X(I,0) = -X(I,1) AND X(I,N+1) = -X(I,N C = 2 IF X(I,0) = -X(I,1) AND X(I,N+1) = X(I,N C = 3 IF X(I,0) = X(I,1) AND X(I,N+1) = X(I,N C = 4 IF X(I,0) = X(I,1) AND X(I,N+1) = -X(I,N C C N C THE NUMBER OF UNKNOWNS IN THE J-DIRECTION. C N MUST BE GREATER THAN 2. C C MPEROD C = 0 IF A(1) AND C(M) ARE NOT ZERO C = 1 IF A(1) = C(M) = 0 C C M C THE NUMBER OF UNKNOWNS IN THE I-DIRECTION. C M MUST BE GREATER THAN 2. C C A,B,C C ONE-DIMENSIONAL ARRAYS OF LENGTH M THAT C SPECIFY THE COEFFICIENTS IN THE LINEAR C EQUATIONS GIVEN ABOVE. IF MPEROD = 0 THE C ARRAY ELEMENTS MUST NOT DEPEND ON INDEX I, C BUT MUST BE CONSTANT. SPECIFICALLY, THE C SUBROUTINE CHECKS THE FOLLOWING CONDITION C A(I) = C(1) C B(I) = B(1) C C(I) = C(1) C FOR I = 1, 2, ..., M. C C IDIMY C THE ROW (OR FIRST) DIMENSION OF THE TWO- C DIMENSIONAL ARRAY Y AS IT APPEARS IN THE C PROGRAM CALLING POISTG. THIS PARAMETER IS C USED TO SPECIFY THE VARIABLE DIMENSION OF Y. C IDIMY MUST BE AT LEAST M. C C Y C A TWO-DIMENSIONAL ARRAY THAT SPECIFIES THE C VALUES OF THE RIGHT SIDE OF THE LINEAR SYSTEM C OF EQUATIONS GIVEN ABOVE. C Y MUST BE DIMENSIONED AT LEAST M X N. C C ON OUTPUT C C Y 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 M .LE. 2 C = 2 IF N .LE. 2 C = 3 IDIMY .LT. M C = 4 IF NPEROD .LT. 1 OR NPEROD .GT. 4 C = 5 IF MPEROD .LT. 0 OR MPEROD .GT. 1 C = 6 IF MPEROD = 0 AND A(I) .NE. C(1) C OR B(I) .NE. B(1) OR C(I) .NE. C(1) C FOR SOME I = 1, 2, ..., M. C = 7 IF MPEROD .EQ. 1 .AND. C (A(1).NE.0 .OR. C(M).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 C C I/O NONE C C PRECISION SINGLE C C REQUIRED files fish.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 THIS SUBROUTINE IS AN IMPLEMENTATION OF THE C ALGORITHM PRESENTED IN THE REFERENCE BELOW. C C TIMING FOR LARGE M AND N, THE EXECUTION TIME IS C ROUGHLY PROPORTIONAL TO M*N*LOG2(N). 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 ABOVE, WITH C A(I) = C(I) = -0.5*B(I) = 1, I=1,2,...,M C AND, WHEN MPEROD = 1 C A(1) = C(M) = 0 C B(1) = B(M) =-1. C C THE SOLUTION X WAS SUBSTITUTED INTO THE GIVEN C SYSTEM AND, USING DOUBLE PRECISION, A RIGHT SID C Y WAS COMPUTED. USING THIS ARRAY Y SUBROUTINE C POISTG WAS CALLED TO PRODUCE AN APPROXIMATE C SOLUTION Z. THEN THE RELATIVE ERROR, DEFINED A C E = MAX(ABS(Z(I,J)-X(I,J)))/MAX(ABS(X(I,J))) C WHERE THE TWO MAXIMA ARE TAKEN OVER I=1,2,...,M C AND J=1,2,...,N, WAS COMPUTED. VALUES OF E ARE C GIVEN IN THE TABLE BELOW FOR SOME TYPICAL VALUE C OF M AND N. C C M (=N) MPEROD NPEROD E C ------ ------ ------ ------ C C 31 0-1 1-4 9.E-13 C 31 1 1 4.E-13 C 31 1 3 3.E-13 C 32 0-1 1-4 3.E-12 C 32 1 1 3.E-13 C 32 1 3 1.E-13 C 33 0-1 1-4 1.E-12 C 33 1 1 4.E-13 C 33 1 3 1.E-13 C 63 0-1 1-4 3.E-12 C 63 1 1 1.E-12 C 63 1 3 2.E-13 C 64 0-1 1-4 4.E-12 C 64 1 1 1.E-12 C 64 1 3 6.E-13 C 65 0-1 1-4 2.E-13 C 65 1 1 1.E-11 C 65 1 3 4.E-13 C C REFERENCES SCHUMANN, U. AND R. SWEET,"A DIRECT METHOD C FOR THE SOLUTION OF POISSON"S EQUATION WITH C NEUMANN BOUNDARY CONDITIONS ON A STAGGERED C GRID OF ARBITRARY SIZE," J. COMP. PHYS. C 20(1976), PP. 171-182. C *********************************************************************