c c file hstcrt.txt (documentation for the FISHPACK solver HSTCRT) 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 * * 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 HSTCRT (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),F(IDIMF,N) C ARGUMENTS C C LATEST REVISION June 2004 C C PURPOSE SOLVES THE STANDARD FIVE-POINT FINITE C DIFFERENCE APPROXIMATION TO THE HELMHOLTZ C EQUATION C (D/DX)(DU/DX) + (D/DY)(DU/DY) + LAMBDA*U C = F(X,Y) C ON A STAGGERED GRID IN CARTESIAN COORDINATES. C C USAGE CALL HSTCRT (A,B,M,MBDCND,BDA,BDB,C,D C N,NBDCND,BDC,BDD,ELMBDA, C F,IDIMF,PERTRB,IERROR) C C ARGUMENTS C ON INPUT C C A,B 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 GRID POINTS IN THE C INTERVAL (A,B). THE GRID POINTS C IN THE X-DIRECTION ARE GIVEN BY C X(I) = A + (I-0.5)DX FOR I=1,2,...,M C WHERE DX =(B-A)/M. M MUST BE GREATER C THAN 2. 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 U(M+I,J) = U(I,J). C C = 1 IF THE SOLUTION IS SPECIFIED AT C X = A AND X = B. C C = 2 IF THE SOLUTION IS SPECIFIED AT C X = A AND THE DERIVATIVE C OF THE SOLUTION WITH RESPECT TO X C IS SPECIFIED AT X = B. C C = 3 IF THE DERIVATIVE OF THE SOLUTION C WITH RESPECT TO X IS SPECIFIED C AT X = A AND X = B. C C = 4 IF THE DERIVATIVE OF THE SOLUTION C WITH RESPECT TO X IS SPECIFIED C AT X = A AND THE SOLUTION IS C SPECIFIED AT X = B. C C BDA C A ONE-DIMENSIONAL ARRAY OF LENGTH N C THAT SPECIFIES THE BOUNDARY VALUES C (IF ANY) OF THE SOLUTION AT X = A. C C WHEN MBDCND = 1 OR 2, C BDA(J) = U(A,Y(J)) , J=1,2,...,N. C C WHEN MBDCND = 3 OR 4, C BDA(J) = (D/DX)U(A,Y(J)) , J=1,2,...,N. C C BDB C A ONE-DIMENSIONAL ARRAY OF LENGTH N C THAT SPECIFIES THE BOUNDARY VALUES C OF THE SOLUTION AT X = B. C C WHEN MBDCND = 1 OR 4 C BDB(J) = U(B,Y(J)) , J=1,2,...,N. C C WHEN MBDCND = 2 OR 3 C BDB(J) = (D/DX)U(B,Y(J)) , J=1,2,...,N. 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 C N C THE NUMBER OF UNKNOWNS IN THE INTERVAL C (C,D). THE UNKNOWNS IN THE Y-DIRECTION C ARE GIVEN BY Y(J) = C + (J-0.5)DY, C J=1,2,...,N, WHERE DY = (D-C)/N. C N MUST BE GREATER THAN 2. C C NBDCND C INDICATES THE TYPE OF BOUNDARY CONDITIONS C AT Y = C AND Y = D. C C C = 0 IF THE SOLUTION IS PERIODIC IN Y, I.E. C U(I,J) = U(I,N+J). C C = 1 IF THE SOLUTION IS SPECIFIED AT Y = C C AND Y = D. C C = 2 IF THE SOLUTION IS SPECIFIED AT Y = C C AND THE DERIVATIVE OF THE SOLUTION C WITH RESPECT TO Y IS SPECIFIED AT C Y = D. C C = 3 IF THE DERIVATIVE OF THE SOLUTION C WITH RESPECT TO Y IS SPECIFIED AT C Y = C AND Y = D. C 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 THAT C SPECIFIES THE BOUNDARY VALUES OF THE C SOLUTION AT Y = C. C C WHEN NBDCND = 1 OR 2, C BDC(I) = U(X(I),C) , I=1,2,...,M. C C WHEN NBDCND = 3 OR 4, C BDC(I) = (D/DY)U(X(I),C), I=1,2,...,M. C C WHEN NBDCND = 0, BDC IS A DUMMY VARIABLE. C C BDD C A ONE-DIMENSIONAL ARRAY OF LENGTH M THAT C SPECIFIES THE BOUNDARY VALUES OF THE C SOLUTION AT Y = D. C C WHEN NBDCND = 1 OR 4, C BDD(I) = U(X(I),D) , I=1,2,...,M. C C WHEN NBDCND = 2 OR 3, C BDD(I) = (D/DY)U(X(I),D) , I=1,2,...,M. C C WHEN NBDCND = 0, BDD IS A DUMMY VARIABLE. C C ELMBDA C THE CONSTANT LAMBDA IN THE HELMHOLTZ C EQUATION. IF LAMBDA IS GREATER THAN 0, C A SOLUTION MAY NOT EXIST. HOWEVER, C HSTCRT WILL ATTEMPT TO FIND A SOLUTION. C C F C A TWO-DIMENSIONAL ARRAY THAT SPECIFIES C THE VALUES OF THE RIGHT SIDE OF THE C HELMHOLTZ EQUATION. FOR I=1,2,...,M C AND J=1,2,...,N C C F(I,J) = F(X(I),Y(J)) . C C F MUST BE DIMENSIONED AT LEAST M X N. C C IDIMF C THE ROW (OR FIRST) DIMENSION OF THE ARRAY C F AS IT APPEARS IN THE PROGRAM CALLING C HSTCRT. THIS PARAMETER IS USED TO SPECIFY C THE VARIABLE DIMENSION OF F. C IDIMF MUST BE AT LEAST M. 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)) FOR I=1,2,...,M, J=1,2,...,N. 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. HSTCRT 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 PROBLEM. C THIS COMPARISON SHOULD ALWAYS BE MADE TO C INSURE THAT A MEANINGFUL SOLUTION HAS BEEN C OBTAINED. C C IERROR C AN ERROR FLAG THAT INDICATES INVALID INPUT C PARAMETERS. EXCEPT TO NUMBERS 0 AND 6, C A SOLUTION IS NOT ATTEMPTED. C C = 0 NO ERROR C C = 1 A .GE. B C C = 2 MBDCND .LT. 0 OR MBDCND .GT. 4 C C = 3 C .GE. D C C = 4 N .LE. 2 C C = 5 NBDCND .LT. 0 OR NBDCND .GT. 4 C C = 6 LAMBDA .GT. 0 C C = 7 IDIMF .LT. M C C = 8 M .LE. 2 C C SINCE THIS IS THE ONLY MEANS OF INDICATING C A POSSIBLY INCORRECT CALL TO HSTCRT, THE C USER SHOULD TEST IERROR AFTER THE CALL. C 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 C I/O NONE C C PRECISION SINGLE C C REQUIRED LIBRARY fish.f,comf.f,genbun.f,gnbnaux.f,poistg.f C FILES C C LANGUAGE FORTRAN 90 C C HISTORY WRITTEN BY ROLAND SWEET AT NCAR IN 1977. C RELEASED ON NCAR'S PUBLIC SOFTWARE LIBRARIES C 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 DEFINES THE FINITE-DIFFERENCE C EQUATIONS, INCORPORATES BOUNDARY DATA, ADJUSTS C THE RIGHT SIDE WHEN THE SYSTEM IS SINGULAR C AND CALLS EITHER POISTG OR GENBUN WHICH SOLVES C THE LINEAR SYSTEM OF EQUATIONS. C C TIMING FOR LARGE M AND N, THE OPERATION COUNT C IS ROUGHLY PROPORTIONAL TO M*N*LOG2(N). C C ACCURACY THE SOLUTION PROCESS EMPLOYED RESULTS IN A C LOSS OF NO MORE THAN FOUR SIGNIFICANT DIGITS C FOR N AND M AS LARGE AS 64. MORE DETAILED C INFORMATION ABOUT ACCURACY CAN BE FOUND IN C THE DOCUMENTATION FOR PACKAGE POISTG WHICH C SOLVES THE FINITE DIFFERENCE EQUATIONS. C C REFERENCES U. SCHUMANN AND R. SWEET,"A DIRECT METHOD C FOR THE SOLUTION OF POISSON'S EQUATION WITH C BOUNDARY CONDITIONS ON A STAGGERED GRID OF C ARBITRARY SIZE," J. COMP. PHYS. 20(1976), C PP. 171-182. C***********************************************************************