# hstcsp.f

          SUBROUTINE HSTCSP (INTL, A, B, M, MBDCND, BDA, BDB, C, D, N,
         +   NBDCND, BDC, BDD, ELMBDA, F, IDIMF, PERTRB, IERROR, W)
    C***BEGIN PROLOGUE  HSTCSP
    C***PURPOSE  Solve the standard five-point finite difference
    C            approximation on a staggered grid to the modified Helmholtz
    C            equation in spherical coordinates assuming axisymmetry
    C            (no dependence on longitude).
    C***LIBRARY   SLATEC (FISHPACK)
    C***CATEGORY  I2B1A1A
    C***TYPE      SINGLE PRECISION (HSTCSP-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     HSTCSP solves the standard five-point finite difference
    C     approximation on a staggered grid to the modified Helmholtz
    C     equation spherical coordinates assuming axisymmetry (no dependence
    C     on longitude).
    C
    C                  (1/R**2)(d/dR)(R**2(dU/dR)) +
    C
    C       1/(R**2*SIN(THETA))(d/dTHETA)(SIN(THETA)(dU/dTHETA)) +
    C
    C            (LAMBDA/(R*SIN(THETA))**2)U  =  F(THETA,R)
    C
    C     where THETA is colatitude and R is the radial coordinate.
    C     This two-dimensional modified Helmholtz equation results from
    C     the Fourier transform of the three-dimensional Poisson equation.
    C
    C    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    C
    C
    C    * * * * * * * *    Parameter Description     * * * * * * * * * *
    C
    C
    C            * * * * * *   On Input    * * * * * *
    C
    C   INTL
    C     = 0  On initial entry to HSTCSP or if any of the arguments
    C          C, D, N, or NBDCND are changed from a previous call.
    C
    C     = 1  If C, D, N, and NBDCND are all unchanged from previous
    C          call to HSTCSP.
    C
    C     NOTE:  A call with INTL = 0 takes approximately 1.5 times as much
    C            time as a call with INTL = 1.  Once a call with INTL = 0
    C            has been made then subsequent solutions corresponding to
    C            different F, BDA, BDB, BDC, and BDD can be obtained
    C            faster with INTL = 1 since initialization is not repeated.
    C
    C   A,B
    C     The range of THETA (colatitude), i.e. A .LE. THETA .LE. B.  A
    C     must be less than B and A must be non-negative.  A and B are in
    C     radians.  A = 0 corresponds to the north pole and B = PI
    C     corresponds to the south pole.
    C
    C                  * * *  IMPORTANT  * * *
    C
    C     If B is equal to PI, then B must be computed using the statement
    C
    C     B = PIMACH(DUM)
    C
    C     This insures that B in the user's program is equal to PI in this
    C     program which permits several tests of the input parameters that
    C     otherwise would not be possible.
    C
    C                  * * * * * * * * * * * *
    C
    C   M
    C     The number of grid points in the interval (A,B).  The grid points
    C     in the THETA-direction are given by THETA(I) = A + (I-0.5)DTHETA
    C     for I=1,2,...,M where DTHETA =(B-A)/M.  M must be greater than 4.
    C
    C   MBDCND
    C     Indicates the type of boundary conditions at THETA = A and
    C     THETA = B.
    C
    C     = 1  If the solution is specified at THETA = A and THETA = B.
    C          (See notes 1, 2 below)
    C
    C     = 2  If the solution is specified at THETA = A and the derivative
    C          of the solution with respect to THETA is specified at
    C          THETA = B (See notes 1, 2 below).
    C
    C     = 3  If the derivative of the solution with respect to THETA is
    C          specified at THETA = A (See notes 1, 2 below) and THETA = B.
    C
    C     = 4  If the derivative of the solution with respect to THETA is
    C          specified at THETA = A (See notes 1, 2 below) and the
    C          solution is specified at THETA = B.
    C
    C     = 5  If the solution is unspecified at THETA = A = 0 and the
    C          solution is specified at THETA = B. (See note 2 below)
    C
    C     = 6  If the solution is unspecified at THETA = A = 0 and the
    C          derivative of the solution with respect to THETA is
    C          specified at THETA = B (See note 2 below).
    C
    C     = 7  If the solution is specified at THETA = A and the
    C          solution is unspecified at THETA = B = PI.
    C
    C     = 8  If the derivative of the solution with respect to
    C          THETA is specified at THETA = A (See note 1 below)
    C          and the solution is unspecified at THETA = B = PI.
    C
    C     = 9  If the solution is unspecified at THETA = A = 0 and
    C          THETA = B = PI.
    C
    C     NOTES:  1.  If A = 0, do not use MBDCND = 1,2,3,4,7 or 8,
    C                 but instead use MBDCND = 5, 6, or 9.
    C
    C             2.  if B = PI, do not use MBDCND = 1,2,3,4,5 or 6,
    C                 but instead use MBDCND = 7, 8, or 9.
    C
    C             When A = 0  and/or B = PI the only meaningful boundary
    C             condition is dU/dTHETA = 0.  (See D. Greenspan, 'Numerical
    C             Analysis of Elliptic Boundary Value Problems,' Harper and
    C             Row, 1965, Chapter 5.)
    C
    C   BDA
    C     A one-dimensional array of length N that specifies the boundary
    C     values (if any) of the solution at THETA = A.  When
    C     MBDCND = 1, 2, or 7,
    C
    C              BDA(J) = U(A,R(J)) ,              J=1,2,...,N.
    C
    C     When MBDCND = 3, 4, or 8,
    C
    C              BDA(J) = (d/dTHETA)U(A,R(J)) ,    J=1,2,...,N.
    C
    C     When MBDCND has any other value, BDA is a dummy variable.
    C
    C   BDB
    C     A one-dimensional array of length N that specifies the boundary
    C     values of the solution at THETA = B.  When MBDCND = 1, 4, or 5,
    C
    C              BDB(J) = U(B,R(J)) ,              J=1,2,...,N.
    C
    C     When MBDCND = 2,3, or 6,
    C
    C              BDB(J) = (d/dTHETA)U(B,R(J)) ,    J=1,2,...,N.
    C
    C     When MBDCND has any other value, BDB is a dummy variable.
    C
    C   C,D
    C     The range of R , i.e. C .LE. R .LE. D.
    C     C must be less than D.  C must be non-negative.
    C
    C   N
    C     The number of unknowns in the interval (C,D).  The unknowns in
    C     the R-direction are given by R(J) = C + (J-0.5)DR,
    C     J=1,2,...,N, where DR = (D-C)/N.  N must be greater than 4.
    C
    C   NBDCND
    C     Indicates the type of boundary conditions at R = C
    C     and R = D.
    C
    C     = 1  If the solution is specified at R = C and R = D.
    C
    C     = 2  If the solution is specified at R = C and the derivative
    C          of the solution with respect to R is specified at
    C          R = D. (See note 1 below)
    C
    C     = 3  If the derivative of the solution with respect to R is
    C          specified at R = C and R = D.
    C
    C     = 4  If the derivative of the solution with respect to R is
    C          specified at R = C and the solution is specified at
    C          R = D.
    C
    C     = 5  If the solution is unspecified at R = C = 0 (See note 2
    C          below) and the solution is specified at R = D.
    C
    C     = 6  If the solution is unspecified at R = C = 0 (See note 2
    C          below) and the derivative of the solution with respect to R
    C          is specified at R = D.
    C
    C     NOTE 1:  If C = 0 and MBDCND = 3,6,8 or 9, the system of equations
    C              to be solved is singular.  The unique solution is
    C              determined by extrapolation to the specification of
    C              U(THETA(1),C).  But in these cases the right side of the
    C              system will be perturbed by the constant PERTRB.
    C
    C     NOTE 2:  NBDCND = 5 or 6 cannot be used with MBDCND = 1, 2, 4, 5,
    C              or 7 (the former indicates that the solution is
    C              unspecified at R = 0; the latter indicates that the
    C              solution is specified).  Use instead NBDCND = 1 or 2.
    C
    C   BDC
    C     A one dimensional array of length M that specifies the boundary
    C     values of the solution at R = C.   When NBDCND = 1 or 2,
    C
    C              BDC(I) = U(THETA(I),C) ,              I=1,2,...,M.
    C
    C     When NBDCND = 3 or 4,
    C
    C              BDC(I) = (d/dR)U(THETA(I),C),         I=1,2,...,M.
    C
    C     When NBDCND has any other value, BDC is a dummy variable.
    C
    C   BDD
    C     A one-dimensional array of length M that specifies the boundary
    C     values of the solution at R = D.  When NBDCND = 1 or 4,
    C
    C              BDD(I) = U(THETA(I),D) ,              I=1,2,...,M.
    C
    C     When NBDCND = 2 or 3,
    C
    C              BDD(I) = (d/dR)U(THETA(I),D) ,        I=1,2,...,M.
    C
    C     When NBDCND has any other value, BDD is a dummy variable.
    C
    C   ELMBDA
    C     The constant LAMBDA in the modified Helmholtz equation.  If
    C     LAMBDA is greater than 0, a solution may not exist.  However,
    C     HSTCSP will attempt to find a solution.
    C
    C   F
    C     A two-dimensional array that specifies the values of the right
    C     side of the modified Helmholtz equation.  For I=1,2,...,M and
    C     J=1,2,...,N
    C
    C              F(I,J) = F(THETA(I),R(J)) .
    C
    C     F must be dimensioned at least M X N.
    C
    C   IDIMF
    C     The row (or first) dimension of the array F as it appears in the
    C     program calling HSTCSP.  This parameter is used to specify the
    C     variable dimension of F.  IDIMF must be at least M.
    C
    C   W
    C     A one-dimensional array that must be provided by the user for
    C     work space.  With K = INT(log2(N))+1 and L = 2**(K+1), W may
    C     require up to (K-2)*L+K+MAX(2N,6M)+4(N+M)+5 locations.  The
    C     actual number of locations used is computed by HSTCSP and is
    C     returned in the location W(1).
    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),R(J)) for
    C     I=1,2,...,M, J=1,2,...,N.
    C
    C   PERTRB
    C     If a combination of periodic, derivative, or unspecified
    C     boundary conditions is specified for a Poisson equation
    C     (LAMBDA = 0), a solution may not exist.  PERTRB is a con-
    C     stant, calculated and subtracted from F, which ensures
    C     that a solution exists.  HSTCSP then computes this
    C     solution, which is a least squares solution to the
    C     original approximation.  This solution plus any constant is also
    C     a solution; hence, the solution is not unique.  The value of
    C     PERTRB should be small compared to the right side F.
    C     Otherwise, a solution is obtained to an essentially different
    C     problem.  This comparison should always be made to insure that
    C     a meaningful solution has been obtained.
    C
    C   IERROR
    C     An error flag that indicates invalid input parameters.
    C     Except for numbers 0 and 10, a solution is not attempted.
    C
    C     =  0  No error
    C
    C     =  1  A .LT. 0 or B .GT. PI
    C
    C     =  2  A .GE. B
    C
    C     =  3  MBDCND .LT. 1 or MBDCND .GT. 9
    C
    C     =  4  C .LT. 0
    C
    C     =  5  C .GE. D
    C
    C     =  6  NBDCND .LT. 1 or NBDCND .GT. 6
    C
    C     =  7  N .LT. 5
    C
    C     =  8  NBDCND = 5 or 6 and MBDCND = 1, 2, 4, 5, or 7
    C
    C     =  9  C .GT. 0 and NBDCND .GE. 5
    C
    C     = 10  ELMBDA .GT. 0
    C
    C     = 11  IDIMF .LT. M
    C
    C     = 12  M .LT. 5
    C
    C     = 13  A = 0 and MBDCND =1,2,3,4,7 or 8
    C
    C     = 14  B = PI and MBDCND .LE. 6
    C
    C     = 15  A .GT. 0 and MBDCND = 5, 6, or 9
    C
    C     = 16  B .LT. PI and MBDCND .GE. 7
    C
    C     = 17  LAMBDA .NE. 0 and NBDCND .GE. 5
    C
    C     Since this is the only means of indicating a possibly
    C     incorrect call to HSTCSP, the user should test IERROR after
    C     the call.
    C
    C   W
    C     W(1) contains the required length of W.  Also  W contains
    C     intermediate values that must not be destroyed if HSTCSP
    C     will be called again with INTL = 1.
    C
    C *Long Description:
    C
    C    * * * * * * *   Program Specifications    * * * * * * * * * * * *
    C
    C    Dimension of   BDA(N),BDB(N),BDC(M),BDD(M),F(IDIMF,N),
    C    Arguments      W(See argument list)
    C
    C    Latest         June 1979
    C    Revision
    C
    C    Subprograms    HSTCSP,HSTCS1,BLKTRI,BLKTR1,INDXA,INDXB,INDXC,
    C    Required       PROD,PRODP,CPROD,CPRODP,PPADD,PSGF,BSRH,PPSGF,
    C                   PPSPF,COMPB,TEVLS,R1MACH
    C
    C    Special        NONE
    C    Conditions
    C
    C    Common         CBLKT
    C    Blocks
    C
    C    I/O            NONE
    C
    C    Precision      Single
    C
    C    Specialist     Roland Sweet
    C
    C    Language       FORTRAN
    C
    C    History        Written by Roland Sweet at NCAR in May, 1977
    C
    C    Algorithm      This subroutine defines the finite-difference
    C                   equations, incorporates boundary data, adjusts the
    C                   right side when the system is singular and calls
    C                   BLKTRI which solves the linear system of equations.
    C
    C    Space          5269(decimal) = 12225(octal) locations on the
    C    Required       NCAR Control Data 7600
    C
    C    Timing and        The execution time T on the NCAR Control Data
    C    Accuracy       7600 for subroutine HSTCSP is roughly proportional
    C                   to M*N*log2(N), but depends on the input parameter
    C                   INTL.  Some values are listed in the table below.
    C                      The solution process employed results in a loss
    C                   of no more than FOUR significant digits for N and M
    C                   as large as 64.  More detailed information about
    C                   accuracy can be found in the documentation for
    C                   subroutine BLKTRI which is the routine that
    C                   actually solves the finite difference equations.
    C
    C
    C                      M(=N)     INTL      MBDCND(=NBDCND)     T(MSECS)
    C                      -----     ----      ---------------     --------
    C
    C                       32        0              1-6             132
    C                       32        1              1-6              88
    C                       64        0              1-6             546
    C                       64        1              1-6             380
    C
    C    Portability    American National Standards Institute Fortran.
    C                   The machine accuracy is set using function R1MACH.
    C
    C    Required       COS,SIN,ABS,SQRT
    C    Resident
    C    Routines
    C
    C    Reference      Swarztrauber, P.N., 'A Direct Method For The
    C                   Discrete Solution Of Separable Elliptic Equations,'
    C                   SIAM J. Numer. Anal. 11(1974), pp. 1136-1150.
    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, A direct method for the discrete
    C                 solution of separable elliptic equations, SIAM Journal
    C                 on Numerical Analysis 11, (1974), pp. 1136-1150.
    C***ROUTINES CALLED  HSTCS1, PIMACH
    C***REVISION HISTORY  (YYMMDD)
    C   801001  DATE WRITTEN
    C   890531  Changed all specific intrinsics to generic.  (WRB)
    C   890531  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  HSTCSP