
          D03 -- Partial Differential Equations         Introduction -- D03
                                    Chapter D03
                          Partial Differential Equations

          1. Scope of the Chapter

          This chapter is concerned with the solution of partial
          differential equations.

          2. Background to the Problems

          The definition of a partial differential equation problem
          includes not only the equation itself but also the domain of
          interest and appropriate subsidiary conditions. Indeed, partial
          differential equations are usually classified as elliptic,
          hyperbolic or parabolic according to the form of the equation and
          the form of the subsidiary conditions which must be assigned to
          produce a well-posed problem. Ultimately it is hoped that this
          chapter will contain routines for the solution of equations of
          each of these types together with automatic mesh generation
          routines and other utility routines particular to the solution of
          partial differential equations. The routines in this chapter will
          often call upon routines from the Linear Algebra Chapter F04 --
          Simultaneous Linear Equations.

          The classification of partial differential equations is easily
          described in the case of linear equations of the second order in
          two independent variables, i.e., equations of the form

                        au  +2bu  +cu  +du +eu +fu+g=0,                 (1)
                          xx    xy   yy   x   y

          where a, b, c, d, e, f and g are functions of x and y only.
          Equation (1) is called elliptic, hyperbolic or parabolic
                           2
          according as ac-b  is positive, negative or zero. Useful
          definitions of the concepts of elliptic, hyperbolic and parabolic
          character can also be given for differential equations in more
          than two independent variables, for systems and for nonlinear
          differential equations.

          For elliptic equations, of which Laplace's equation

                                   u  +u  =0                            (2)
                                    xx  yy

          is the simplest example of second order, the subsidiary
          conditions take the form of boundary conditions, i.e., conditions
          which provide information about the solution at all points of a
          closed boundary. For example, if equation (2) holds in a plane
          domain D bounded by a contour C, a solution u may be sought
          subject to the condition

                                   u=f  on C,                           (3)

          where f is a given function. The condition (3) is known as a
          Dirichlet boundary condition. Equally common is the Neumann
          boundary condition

                                  u'=g  on C,                           (4)

          which is one form of a more general condition

                                 u'+fu=g  on C,                         (5)

          where u' denotes the derivative of u normal to the contour C and
          f and g are given functions. Provided that f and g satisfy
          certain restrictions, condition (5) yields a well-posed  boundary
          value problem  for Laplace's equation. In the case of the Neumann
          problem, one further piece of information, e.g. the value of u at
          a particular point, is necessary for uniqueness of the solution.
          Boundary conditions similar to the above are applicable to more
          general second order elliptic equations, whilst two such
          conditions are required for equations of fourth order.

          For hyperbolic equations, the wave equation

                                   u  -u  =0                            (6)
                                    tt  xx

          is the simplest example of second order. It is equivalent to a
          first order system

                               u -v =0,  v -u =0.                       (7)
                                t  x      t  x

          The subsidiary conditions may take the form of initial
          conditions, i.e., conditions which provide information about the
          solution at points on a suitable open boundary. For example, if
          equation (6) is satisfied for t>0, a solution u may be sought
          such that

                          u(x,0)=f(x),  u (x,0)=g(x),                   (8)
                                         t

          where f and g are given functions. This is an example of an
          initial value problem, sometimes known as Cauchy's problem.

          For parabolic equations, of which the heat conduction equation

                                    u -u  =0                            (9)
                                     t  xx

          is the simplest example, the subsidiary conditions always include
          some of initial type and may also include some of boundary type.
          For example, if equation (9) is satisfied for t>0 and 0<x<1, a
          solution u may be sought such that

                             u(x,0)=f(x),  0<x<1,                      (10)

          and

                          u(0,t)=0,  u(1,t)=1,  t>0.                   (11)

          This is an example of a mixed  initial/boundary value problem.

          For all types of partial differential equations, finite
          difference methods (Mitchell and Griffiths [5]) and finite
          element methods (Wait and Mitchell [9]) are the most common means
          of solution and such methods obviously feature prominently either
          in this chapter or in the companion NAG Finite Element Library.
          Many of the utility routines in this chapter are concerned with
          the solution of the large sparse systems of equations which arise
          from the finite difference and finite element methods.

          Alternative methods of solution are often suitable for special
          classes of problems. For example, the method of characteristics
          is the most common for hyperbolic equations involving time and
          one space dimension (Smith [7]). The method of lines (see Mikhlin
          and Smolitsky [4]) may be used to reduce a parabolic equation to
          a (stiff) system of ordinary differential equations, which may be
          solved by means of routines from Chapter D02 -- Ordinary
          Differential Equations. Similarly, integral equation or boundary
          element methods (Jaswon and Symm [3]) are frequently used for
          elliptic equations. Typically, in the latter case, the solution
          of a boundary value problem is represented in terms of certain
          boundary functions by an integral expression which satisfies the
          differential equation throughout the relevant domain. The
          boundary functions are obtained by applying the given boundary
          conditions to this representation. Implementation of this method
          necessitates discretisation of only the boundary of the domain,
          the dimensionality of the problem thus being effectively reduced
          by one. The boundary conditions yield a full system of
          simultaneous equations, as opposed to the sparse systems yielded
          by the finite difference and finite element methods, but the full
          system is usually of much lower order. Solution of this system
          yields the boundary functions, from which the solution of the
          problem may be obtained, by quadrature, as and where required.

          2.1. References

          [1]   Ames W F (1977) Nonlinear Partial Differential Equations in
                Engineering. Academic Press (2nd Edition).

          [2]   Berzins M (1990) Developments in the NAG Library Software
                for Parabolic Equations. Scientific Software Systems. (ed J
                C Mason and M G Cox) Chapman and Hall. 59--72.

          [3]   Jaswon M A and Symm G T (1977) Integral Equation Methods in
                Potential Theory and Elastostatics. Academic Press.

          [4]   Mikhlin S G and Smolitsky K L (1967) Approximate Methods for
                the Solution of Differential and Integral Equations.
                Elsevier.

          [5]   Mitchell A R and Griffiths D F (1980) The Finite Difference
                Method in Partial Differential Equations. Wiley.

          [6]   Richtmyer R D and Morton K W (1967) Difference Methods for
                Initial-value Problems. Interscience (2nd Edition).

          [7]   Smith G D (1985) Numerical Solution of Partial Differential
                Equations: Finite Difference Methods. Oxford University
                Press (3rd Edition).

          [8]   Swarztrauber P N and Sweet R A (1979) Efficient Fortran
                Subprograms for the Solution of Separable Elliptic Partial
                Differential Equations. ACM Trans. Math. Softw. 5 352--364.

          [9]   Wait R and Mitchell A R (1985) Finite Element Analysis and
                Application. Wiley.

          3. Recommendations on Choice and Use of Routines

          The choice of routine will depend first of all upon the type of
          partial differential equation to be solved. At present no special
          allowances are made for problems with boundary singularities such
          as may arise at corners of domains or at points where boundary
          conditions change. For such problems results should be treated
          with caution.

          Users may wish to construct their own partial differential
          equation solution software for problems not solvable by the
          routines described in Sections 3.1 to 3.4 below. In such cases
          users can employ appropriate routines from the Linear Algebra
          Chapters to solve the resulting linear systems; see Section 3.5
          for further details.

          3.1. Elliptic Equations

          The routine D03EDF solves a system of seven-point difference
          equations in a rectangular grid (in two dimensions), using the
          multigrid iterative method. The equations are supplied by the
          user, and the seven-point form allows cross-derivative terms to
          be represented (see Mitchell and Griffiths [5]). The method is
          particularly efficient for large systems of equations with
          diagonal dominance.

          The routine D03EEF discretises a second-order equation on a two-
          dimensional rectangular region using finite differences and a
          seven-point molecule. The routine allows for cross-derivative
          terms, Dirichlet, Neumann or mixed boundary conditions, and
          either central or upwind differences. The resulting seven-
          diagonal difference equations are in a form suitable for passing
          directly to the multigrid routine D03EDF, although other solution
          methods could easily be used.

          The routine D03FAF, based on the routine HW3CRT from FISHPACK
          (Swarztrauber and Sweet [8]), solves the Helmholtz equation in a
          three-dimensional cuboidal region, with any combination of
          Dirichlet, Neumann or periodic boundary conditions. The method
          used is based on the fast Fourier transform algorithm, and is
          likely to be particularly efficient on vector-processing
          machines.

          3.2. Hyperbolic Equations

          There are no routines available yet for the solution of these
          equations.

          3.3. Parabolic Equations

          There are no routines available yet for the solution of these
          equations.

          But problems in two space dimensions plus time may be treated as
          a succession of elliptic equations [1], [6] using appropriate
          D03E- routines or one may use codes from the NAG Finite Element
          Library.

          3.4. Utility Routines

          There are no utility routines available yet, but routines are
          available in the Linear Algebra Chapters for the direct and
          iterative solution of linear equations. Here we point to some of
          the routines that may be of use in solving the linear systems
          that arise from finite difference or finite element
          approximations to partial differential equation solutions.
          Chapters F01 and F04 should be consulted for further information
          and for the routine documents. Decision trees for the solution of
          linear systems are given in Section 3.5 of the F04 Chapter
          Introduction.

          The following routines allow the direct solution of symmetric
          positive-definite systems:

              Band               F04ACF

              Variable band      F01MCF and F04MCF
              (skyline)

              Tridiagonal        F04FAF

              Sparse             F01MAF* and F04MAF

          (* the parameter DROPTL should be set to zero for F01MAF to give
          a direct solution)

          and the following routines allow the iterative solution of
          symmetric positive-definite systems:

              Sparse (incomplete F01MAF and F04MBF
              Cholesky)

              Sparse (conjugate  F04MBF
              gradient)

          The latter routine above allows the user to supply a pre-
          conditioner and also allows the solution of indefinite symmetric
          systems.

          The following routines allow the direct solution of unsymmetric
          systems:

              Band               F01LBF and F04LDF

              Almost block-      F01LHF and F04LHF
              diagonal

              Tridiagonal        F01LEF and F04LEF or F04EAF

              Sparse             F01BRF (and F01BSF) and F04AXF

          and the following routine allows the iterative solution of
          unsymmetric systems:

              Sparse             F04QAF

          The above routine allows the user to supply a pre-conditioner and
          also allows the solution of least-squares systems.

          3.5. Index

          Elliptic equations
               equations on rectangular grid (seven-point 2-D        D03EDF
               molecule)
               discretisation on rectangular grid (seven-point 2-D   D03EEF
               molecule)
               Helmholtz's equation in three dimensions              D03FAF



          D03 -- Partial Differential Equations             Contents -- D03
          Chapter D03

          Partial Differential Equations

          D03EDF  Elliptic PDE, solution of finite difference equations by
                  a multigrid technique

          D03EEF  Discretize a 2nd order elliptic PDE on a rectangle

          D03FAF  Elliptic PDE, Helmholtz equation, 3-D Cartesian co-
                  ordinates

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          D03 -- Partial Differential Equations                      D03EDF
                  D03EDF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          D03EDF solves seven-diagonal systems of linear equations which
          arise from the discretization of an elliptic partial differential
          equation on a rectangular region. This routine uses a multigrid
          technique.

          2. Specification

                 SUBROUTINE D03EDF (NGX, NGY, LDA, A, RHS, UB, MAXIT, ACC,
                1                   US, U, IOUT, NUMIT, IFAIL)
                 INTEGER          NGX, NGY, LDA, MAXIT, IOUT, NUMIT, IFAIL
                 DOUBLE PRECISION A(LDA,7), RHS(LDA), UB(NGX*NGY), ACC, US
                1                 (LDA), U(LDA)

          3. Description

          D03EDF solves, by multigrid iteration, the seven-point scheme

           6            7
          A   u       +A   u
           i,j i-1,j+1  i,j i,j+1

            3           4        5
          +A   u      +A   u   +A   u
            i,j i-1,j   i,j ij   i,j i+1,j

                        1          2
                      +A   u     +A   u        =f  ,
                        i,j i,j-1  i,j i+1,j-1  ij

                                               i=1,2,...,n ; j=1,2,...,n ,
                                                          x             y

          which arises from the discretization of an elliptic partial
          differential equation of the form


          (alpha)(x,y)U  +(beta)(x,y)U  +(gamma)(x,y)U  +(delta)(x,y)U
                       xx             xy              yy              x

          +(epsilon)(x,y)U +(phi)(x,y)U=(psi)(x,y)
                          y

          and its boundary conditions, defined on a rectangular region.
          This we write in matrix form as

                                        Au=f

          The algorithm is described in separate reports by Wesseling [2],
          [3] and McCarthy [1].

          Systems of linear equations, matching the seven-point stencil
          defined above, are solved by a multigrid iteration. An initial
          estimate of the solution must be provided by the user. A zero
          guess may be supplied if no better approximation is available.

          A 'smoother' based on incomplete Crout decomposition is used to
          eliminate the high frequency components of the error. A
          restriction operator is then used to map the system on to a
          sequence of coarser grids. The errors are then smoothed and
          prolongated (mapped onto successively finer grids). When the
          finest cycle is reached, the approximation to the solution is
          corrected. The cycle is repeated for MAXIT iterations or until
          the required accuracy, ACC, is reached.

          D03EDF will automatically determine the number l of possible
          coarse grids, 'levels' of the multigrid scheme, for a particular
          problem. In other words, D03EDF determines the maximum integer l
          so that n  and n  can be expressed in the form
                   x      y

                        l-1          l-1
                   n =m2   +1,  n =n2   +1,  with  m>=2 and n>=2.
                    x            y

          It should be noted that the rate of convergence improves
          significantly with the number of levels used (see McCarthy [1]),
          so that n  and n  should be carefully chosen so that n -1 and
                   x      y                                     x
                                         l
          n -1 have factors of the form 2 , with l as large as possible.
           y
          For good convergence the integer l should be at least 2.

          D03EDF has been found to be robust in application, but being an
          iterative method the problem of divergence can arise. For a
          strictly diagonally dominant matrix A

                                   4           k
                                    ij   --     ij
                                 |A   |> >   |A   |
                                         --
                                         k/=4

          no such problem is foreseen. The diagonal dominance of A is not a
          necessary condition, but should this condition be strongly
          violated then divergence may occur. The quickest test is to try
          the routine.

          4. References

          [1]   McCarthy G J (1983) Investigation into the Multigrid Code
                MGD1. Report AERE-R 10889. Harwell.

          [2]   Wesseling P (1982) MGD1 - A Robust and Efficient Multigrid
                Method. Multigrid Methods. Lecture Notes in Mathematics. 960
                Springer-Verlag. 614--630.

          [3]   Wesseling P (1982) Theoretical Aspects of a Multigrid
                Method. SIAM J. Sci. Statist. Comput. 3 387--407.

          5. Parameters

           1:  NGX -- INTEGER                                         Input
               On entry: the number of interior grid points in the x-
               direction, n . NGX-1 should preferably be divisible by as
                           x
               high a power of 2 as possible. Constraint: NGX >= 3.

           2:  NGY -- INTEGER                                         Input
               On entry: the number of interior grid points in the y-
               direction, n . NGY-1 should preferably be divisible by as
                           y
               high a power of 2 as possible. Constraint: NGY >= 3.

           3:  LDA -- INTEGER                                         Input
               On entry: the first dimension of the array A as declared in
               the (sub)program from which D03EDF is called, which must
               also be a lower bound for the dimensions of the arrays RHS,
               US and U. It is always sufficient to set
               LDA>=(4*(NGX+1)*(NGY+1))/3, but slightly smaller values may
               be permitted, depending on the values of NGX and NGY. If on
               entry, LDA is too small, an error message gives the minimum
               permitted value. (LDA must be large enough to allow space
               for the coarse-grid approximations).

           4:  A(LDA,7) -- DOUBLE PRECISION array              Input/Output
                                                           k
               On entry: A(i+(j-1)*NGX,k) must be set to  A  ,   for i =
                                                           ij
               1,2,...,NGX; j = 1,2,...,NGY and k = 1,2,...,7. On exit: A
               is overwritten.

           5:  RHS(LDA) -- DOUBLE PRECISION array              Input/Output
               On entry: RHS(i+(j-1)*NGX) must be set to f  , for i =
                                                           ij
               1,2,...,NGX; j = 1,2,...,NGY. On exit: the first NGX*NGY
               elements are unchanged and the rest of the array is used as
               workspace.

           6:  UB(NGX*NGY) -- DOUBLE PRECISION array           Input/Output
               On entry: UB(i+(j-1)*NGX) must be set to the initial
               estimate for the solution u  . On exit: the corresponding
                                          ij
               component of the residual r=f-Au.

           7:  MAXIT -- INTEGER                                       Input
               On entry: the maximum permitted number of multigrid
               iterations. If MAXIT = 0, no multigrid iterations are
               performed, but the coarse-grid approximations and incomplete
               Crout decompositions are computed, and may be output if IOUT
               is set accordingly. Constraint: MAXIT >= 0.

           8:  ACC -- DOUBLE PRECISION                                Input
               On entry: the required tolerance for convergence of the
               residual 2-norm:
                                              

                                             / NGX*NGY
                                            /  --         2
                                 ||r|| =   /   >      (r )
                                      2   /    --       k
                                        \/     k=1
               where r=f-Au and u is the computed solution. Note that the
               norm is not scaled by the number of equations. The routine
               will stop after fewer than MAXIT iterations if the residual
               2-norm is less than the specified tolerance. (If MAXIT > 0,
               at least one iteration is always performed.)

               If on entry ACC = 0.0, then the machine precision is used as
               a default value for the tolerance; if ACC > 0.0, but ACC is
               less than the machine precision, then the routine will stop
               when the residual 2-norm is less than the machine precision
               and IFAIL will be set to 4. Constraint: ACC >= 0.0.

           9:  US(LDA) -- DOUBLE PRECISION array                     Output
               On exit: the residual 2-norm, stored in element US(1).

          10:  U(LDA) -- DOUBLE PRECISION array                      Output
               On exit: the computed solution u   is returned in U(i+(j-
                                                ij
               1)*NGX), for i = 1,2,...,NGX; j = 1,2,...,NGY.

          11:  IOUT -- INTEGER                                        Input
               On entry: controls the output of printed information to the
               advisory message unit as returned by X04ABF:
               IOUT = 0
                     No output.

               IOUT = 1
                     The solution u  , for i = 1,2,...,NGX; j = 1,2,...
                                   ij
                     ,NGY.

               IOUT = 2
                     The residual 2-norm after each iteration, with the
                     reduction factor over the previous iteration.

               IOUT = 3
                     As for IOUT = 1 and IOUT = 2.

               IOUT = 4
                     As for IOUT = 3, plus the final residual (as returned
                     in UB).

               IOUT = 5
                     As for IOUT = 4, plus the initial elements of A and
                     RHS.

               IOUT = 6
                     As for IOUT = 5, plus the Galerkin coarse grid
                     approximations.

               IOUT = 7
                     As for IOUT = 6, plus the incomplete Crout
                     decompositions.

               IOUT = 8
                     As for IOUT = 7, plus the residual after each
                     iteration.
               The elements A(p,k), the Galerkin coarse grid approximations
               and the incomplete Crout decompositions are output in the
               format:
                    Y-index = j

                    X-index = i A(p,1) A(p,2) A(p,3) A(p,4) A(p,5) A(p,6)
                    A(p,7)

                    where p=i+(j-1)*NGX, i = 1,2,...,NGX and j = 1,2,...
                    ,NGY.
               The vectors U(p), UB(p), RHS(p) are output in matrix form
               with NGY rows and NGX columns. Where NGX > 10, the NGX
               values for a given j-value are produced in rows of 10.
               Values of IOUT > 4 may yield considerable amounts of output.
               Constraint: 0 <= IOUT <= 8.

          12:  NUMIT -- INTEGER                                      Output
               On exit: the number of iterations performed.

          13:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry NGX < 3,

               or       NGY < 3,

               or       LDA is too small,

               or       ACC < 0.0,

               or       MAXIT < 0,

               or       IOUT < 0,

               or       IOUT > 8.

          IFAIL= 2
               MAXIT iterations have been performed with the residual 2-
               norm decreasing at each iteration but the residual 2-norm
               has not been reduced to less than the specified tolerance
               (see ACC). Examine the progress of the iteration by setting
               IOUT >= 2.

          IFAIL= 3
               As for IFAIL = 2, except that at one or more iterations the
               residual 2-norm did not decrease. It is likely that the
               method fails to converge for the given matrix A.

          IFAIL= 4
               On entry ACC is less than the machine precision. The routine
               terminated because the residual norm is less than the
               machine precision.

          7. Accuracy

          See ACC (Section 5).

          8. Further Comments

          The rate of convergence of this routine is strongly dependent
          upon the number of levels, l, in the multigrid scheme, and thus
          the choice of NGX and NGY is very important. The user is advised
          to experiment with different values of NGX and NGY to see the
          effect they have on the rate of convergence; for example, using a
                                    6
          value such as NGX = 65 (=2 +1) followed by NGX = 64 (for which l
          = 1).

          9. Example

          The program solves the elliptic partial differential equation

                        U  -(alpha)U  +U  =-4,   (alpha)=1.7
                         xx         xy  yy

          on the unit square 0<=x,y<=1, with boundary conditions

                           {x=0, (0<=y<=1)
                    U=0 on {y=0, (0<=x<=1) U=1 on x=1,  0<=y<=1.
                           {y=1, (0<=x<=1)

          For the equation to be elliptic, (alpha) must be less than 2.

          The equation is discretized on a square grid with mesh spacing h
          in both directions using the following approximations:



                   Please see figure in printed Reference Manual

                                       1
                                 U  ~= --(U -2U +U )
                                  xx    2  E   O  W
                                       h

                                       1
                                 U  ~= --(U -2U +U )
                                  yy    2  N   O  S
                                       h

                                1
                         U  ~= ---(U -U  +U -2U +U -U  +U ).
                          xy     2  N  NW  E   O  W  SE  S
                               2h

          Thus the following equations are solved:


              1                      1
              -(alpha)u        + (1- -(alpha))u
              2        i-1,j+1       2         i,j+1

               1                                           1

          +(1- -(alpha))u      + (-4+(alpha))u       + (1- -(alpha))u
               2         i-1,j                ij           2         i+1,j

                                     1                  1
                               + (1- -(alpha))u      +  -(alpha)u
                                     2         i,j-1    2        i+1,j-1

                    2
                =-4h

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          D03 -- Partial Differential Equations                      D03EEF
                  D03EEF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          D03EEF discretizes a second order elliptic partial differential
          equation (PDE) on a rectangular region.

          2. Specification

                 SUBROUTINE D03EEF (XMIN, XMAX, YMIN, YMAX, PDEF, BNDY,
                1                   NGX, NGY, LDA, A, RHS, SCHEME, IFAIL)
                 INTEGER          NGX, NGY, LDA, IFAIL
                 DOUBLE PRECISION XMIN, XMAX, YMIN, YMAX, A(LDA,7), RHS(LDA)
                 CHARACTER*1      SCHEME
                 EXTERNAL         PDEF, BNDY

          3. Description

          D03EEF discretizes a second order linear elliptic partial
          differential equation of the form


                         2                 2                  2
                       dd U              dd U               dd U
          (alpha)(x,y) ----+(beta)(x,y) ------+(gamma)(x,y) ----
                         2              ddxddy                2
                       dd x                                 dd y

                        ddU                ddU
          +(delta)(x,y) ---+(epsilon)(x,y) ---+(phi)(x,y)U=(psi)(x,y)   (1)
                        ddx                ddy


          on a rectangular region

                                      x <=x<=x
                                       A      B

                                      y <=y<=y
                                       A      B

          subject to boundary conditions of the form

                                             ddU
                              a(x,y)U+b(x,y) ---=c(x,y)
                                             ddn

                 ddU
          where  --- denotes the outward pointing normal derivative on the
                 ddn
          boundary. Equation (1) is said to be elliptic if

                                                              2
                      4(alpha)(x,y)(gamma)(x,y)>=((beta)(x,y))

          for all points in the rectangular region. The linear equations
          produced are in a form suitable for passing directly to the
          multigrid routine D03EDF.

          The equation is discretized on a rectangular grid, with n  grid
                                                                   x
          points in the x-direction and n  grid points in the y-direction.
                                         y
          The grid spacing used is therefore

                                  h =(x -x )/(n -1)
                                   x   B  A    x

                                  h =(y -y )/(n -1)
                                   y   B  A    y

          and the co-ordinates of the grid points (x ,y ) are
                                                    i  j

                            x =x +(i-1)h ,  i=1,2,...,n ,
                             i  A       x              x

                            y =y +(j-1)h ,  j=1,2,...,n .
                             j  A       y              y

          At each grid point (x ,y ) six neighbouring grid points are used
                               i  j
          to approximate the partial differential equation, so that the
          equation is discretized on the following seven-point stencil:



                   Please see figure in printed Reference Manual

          For convenience the approximation u   to the exact solution
                                             ij
          U(x ,y ) is denoted by u , and the neighbouring approximations
             i  j                 O
          are labelled according to points of the compass as shown. Where
          numerical labels for the seven points are required, these are
          also shown above.

          The following approximations are used for the second derivatives:

                 2
               dd U   1
               ----~= --(u -2u +u )
                 2     2  E   O  W
               dd x   h
                       x

                 2
               dd U   1
               ----~= --(u -2u +u )
                 2     2  N   O  S
               dd y   h
                       y

                  2
                dd U    1
               ------~= -----(u -u  +u -2u +u -u  +u ).
               ddxddy 2h h   N  NW  E   O  W  SE  S
                        x y

          Two possible schemes may be used to approximate the first
          derivatives:

          Central Differences

               ddU     1
               ---~=  ---(u -u )
               ddx    2h   W  E
                        x

               ddU     1
               ---~=  ---(u -u )
               ddy    2h   N  S
                        y

          Upwind Differences

               ddU    1
               ---~=  --(u -u )if (delta)(x,y)>0
               ddx    h   E  O
                       x

               ddU    1
               ---~=  --(u -u )if (delta)(x,y)<0
               ddx    h   O  W
                       x

               ddU    1
               ---~=  --(u -u )if (epsilon)(x,y)>0
               ddy    h   N  O
                       y

               ddU    1
               ---~=  --(u -u )if (epsilon)(x,y)<0.
               ddy    h   O  S
                       y

          Central differences are more accurate than upwind differences,
          but upwind differences may lead to a more diagonally dominant
          matrix for those problems where the coefficients of the first
          derivatives are significantly larger than the coefficients of the
          second derivatives.

          The approximations used for the first derivatives may be written
          in a more compact form as follows:

               ddU     1
               ---~=  ---((k -1)u -2k u +(k +1)u )
               ddx    2h (  x    W   x O   x    E)
                        x

               ddU     1
               ---~=  ---((k -1)u -2k u +(k +1)u )
               ddy    2h (  y    S   y O   y    N)
                        y

          where k =sign (delta) and k =sign (epsilon) for upwind
                 x                   y
          differences, and k =k =0 for central differences.
                            x  y

          At all points in the rectangular domain, including the boundary,
          the coefficients in the partial differential equation are
          evaluated by calling the user-supplied subroutine PDEF, and
          applying the approximations. This leads to a seven-diagonal
          system of linear equations of the form:

              6            7
             A  u        +A  u
              ij i-1,j+1   ij i,j+1
               3          4       5
             +A  u      +A  u   +A  u
               ij i-1,j   ij ij   ij i+1,j
                 1          2
               +A  u      +A  u        =f  , i=1,2,...,n ;j=1,2,...,n ,
                 ij i,j-1   ij i+1,j-1   ij             x            y

          where the coefficients are given by

           1                 1                   1                   1
          A  =(beta)(x ,y )----- +(gamma)(x ,y )-- +(epsilon)(x ,y )---(k -1)
           ij         i  j 2h h            i  j  2             i  j 2h   y
                             x y                h                     y
                                                 y
           2                   1
          A  =-(beta)(x ,y ) -----
           ij          i  j  2h h
                               x y

           3                 1                  1                   1
          A  =(alpha)(x ,y ) --+(beta)(x ,y ) -----+(delta)(x ,y ) ---(k -1)
           ij          i  j   2         i  j  2h h           i  j  2h   x
                             h                  x y                  x
                              x

           4                  2                  1                   2
          A  =-(alpha)(x ,y ) -- -(beta)(x ,y ) ---- -(gamma)(x ,y ) --
           ij           i  j   2          i  j  h h            i  j   2
                              h                  x y                 h
                               x                                      y

                              k                    k
                               y                    y
              -(delta)(x ,y ) -- -(epsilon)(x ,y ) -- -(phi)(x ,y )
                        i  j  h              i  j  h          i  j
                               x                    y

           5                 1                  1                   1
          A  =(alpha)(x ,y ) --+(beta)(x ,y ) -----+(delta)(x ,y ) ---(k +1)
           ij          i  j   2         i  j  2h h           i  j  2h   x
                             h                  x y                  x
                              x

           6                   1
          A  =-(beta)(x ,y ) -----
           ij          i  j  2h h
                               x y

           7                 1                  1                   1
          A  =(beta)(x ,y )-----+(gamma)(x ,y )--+(epsilon)(x ,y )---(k +1)
           ij         i  j 2h h           i  j  2             i j 2h   y
                             x y               h                    y
                                                y

          f  =(psi)(x ,y )
           ij        i  j

          These equations then have to be modified to take account of the
          boundary conditions. These may be Dirichlet (where the solution
          is given), Neumann (where the derivative of the solution is
          given), or mixed (where a linear combination of solution and
          derivative is given).

          If the boundary conditions are Dirichlet, there are an infinity
          of possible equations which may be applied:

                           (mu)u  =(mu)f   , (mu)/=0.                   (2)
                                ij      ij

          If D03EDF is used to solve the discretized equations, it turns
          out that the choice of (mu) can have a dramatic effect on the
          rate of convergence, and the obvious choice (mu)=1 is not the
          best. Some choices may even cause the multigrid method to fail
          altogether. In practice it has been found that a value of the
          same order as the other diagonal elements of the matrix is best,
          and the following value has been found to work well in practice:

                                       ( { 2   2 }  4 )
                             (mu)=min  (-{ --+ --},A  ).
                                     ij( {  2   2}  ij)
                                       ( { h   h }    )
                                       ( {  x   y}    )

          If the boundary conditions are either mixed or Neumann (i.e., B
          /= 0 on return from the user-supplied subroutine BNDY), then one
          of the points in the seven-point stencil lies outside the domain.
          In this case the normal derivative in the boundary conditions is
          used to eliminate the 'fictitious' point, u       :
                                                     outside

                           ddU   1
                           ---~= --(u       -u      ).                  (3)
                           ddn   2h  outside  inside

          It should be noted that if the boundary conditions are Neumann
          and (phi)(x,y)==0, then there is no unique solution. The routine
          returns with IFAIL = 5 in this case, and the seven-diagonal
          matrix is singular.

          The four corners are treated separately. The user-supplied
          subroutine BNDY is called twice, once along each of the edges
          meeting at the corner. If both boundary conditions at this point
          are Dirichlet and the prescribed solution values agree, then this
          value is used in an equation of the form (2). If the prescribed
          solution is discontinuous at the corner, then the average of the
          two values is used. If one boundary condition is Dirichlet and
          the other is mixed, then the value prescribed by the Dirichlet
          condition is used in an equation of the form given above.
          Finally, if both conditions are mixed or Neumann, then two '
          fictitious' points are eliminated using two equations of the form
          (3).

          It is possible that equations for which the solution is known at
          all points on the boundary, have coefficients which are not
          defined on the boundary. Since this routine calls the user-
          supplied subroutine PDEF at all points in the domain, including
          boundary points, arithmetic errors may occur in the user's
          routine PDEF which this routine cannot trap. If the user has an
          equation with Dirichlet boundary conditions (i.e., B = 0 at all
          points on the boundary), but with PDE coefficients which are
          singular on the boundary, then D03EDF could be called directly
          only using interior grid points with the user's own
          discretization.

          After the equations have been set up as described above, they are
          checked for diagonal dominance. That is to say,

                     4     --    k
                   |A  | > >   |A  |,  i=1,2,...,n ; j=1,2,...,n .
                     ij    --    ij               x             y
                           k/=4

          If this condition is not satisfied then the routine returns with
          IFAIL = 6. The multigrid routine D03EDF may still converge in
          this case, but if the coefficients of the first derivatives in
          the partial differential equation are large compared with the
          coefficients of the second derivative, the user should consider
          using upwind differences (SCHEME = 'U').

          Since this routine is designed primarily for use with D03EDF,
          this document should be read in conjunction with the document for
          that routine.

          4. References

          [1]   Wesseling P (1982) MGD1 - A Robust and Efficient Multigrid
                Method. Multigrid Methods. Lecture Notes in Mathematics. 960
                Springer-Verlag. 614--630.

          5. Parameters

           1:  XMIN -- DOUBLE PRECISION                               Input

           2:  XMAX -- DOUBLE PRECISION                               Input
               On entry: the lower and upper x co-ordinates of the
               rectangular region respectively, x  and x . Constraint: XMIN
                                                 A      B
               < XMAX.

           3:  YMIN -- DOUBLE PRECISION                               Input

           4:  YMAX -- DOUBLE PRECISION                               Input
               On entry: the lower and upper y co-ordinates of the
               rectangular region respectively, y  and y . Constraint: YMIN
                                                 A      B
               < YMAX.

           5:  PDEF -- SUBROUTINE, supplied by the user.
                                                         External Procedure
               PDEF must evaluate the functions (alpha)(x,y), (beta)(x,y),
               (gamma)(x,y), (delta)(x,y), (epsilon)(x,y), (phi)(x,y) and
               (psi)(x,y) which define the equation at a general point
               (x,y).

               Its specification is:

                      SUBROUTINE PDEF (X, Y, ALPHA, BETA, GAMMA,
                     1                 DELTA, EPSLON, PHI, PSI)
                      DOUBLE PRECISION X, Y, ALPHA, BETA, GAMMA, DELTA,
                     1                 EPSLON, PHI, PSI

                1:  X -- DOUBLE PRECISION                             Input

                2:  Y -- DOUBLE PRECISION                             Input
                    On entry: the x and y co-ordinates of the point at
                    which the coefficients of the partial differential
                    equation are to be evaluated. 8

                3:  ALPHA -- DOUBLE PRECISION                        Output

                4:  BETA -- DOUBLE PRECISION                         Output

                5:  GAMMA -- DOUBLE PRECISION                        Output

                6:  DELTA -- DOUBLE PRECISION                        Output

                7:  EPSLON -- DOUBLE PRECISION                       Output

                8:  PHI -- DOUBLE PRECISION                          Output

                9:  PSI -- DOUBLE PRECISION                          Output
                    On exit: ALPHA, BETA, GAMMA, DELTA, EPSLON, PHI and PSI
                    must be set to the values of (alpha)(x,y), (beta)(x,y),
                    (gamma)(x,y), (delta)(x,y), (epsilon)(x,y), (phi)(x,y)
                    and (psi)(x,y) respectively at the point specified by X
                    and Y.
               PDEF must be declared as EXTERNAL in the (sub)program
               from which D03EEF is called. Parameters denoted as
               Input must not be changed by this procedure.

           6:  BNDY -- SUBROUTINE, supplied by the user.
                                                         External Procedure
               BNDY must evaluate the functions a(x,y), b(x,y), and c(x,y)
               involved in the boundary conditions.

               Its specification is:

                      SUBROUTINE BNDY (X, Y, A, B, C, IBND)
                      INTEGER          IBND
                      DOUBLE PRECISION X, Y, A, B, C

                1:  X -- DOUBLE PRECISION                             Input

                2:  Y -- DOUBLE PRECISION                             Input
                    On entry: the x and y co-ordinates of the point at
                    which the boundary conditions are to be evaluated.

                3:  A -- DOUBLE PRECISION                            Output

                4:  B -- DOUBLE PRECISION                            Output

                5:  C -- DOUBLE PRECISION                            Output
                    On exit: A, B and C must be set to the values of the
                    functions appearing in the boundary conditions.

                6:  IBND -- INTEGER                                   Input
                    On entry: specifies on which boundary the point (X,Y)
                    lies. IBND = 0, 1, 2 or 3 according as the point lies
                    on the bottom, right, top or left boundary.
               BNDY must be declared as EXTERNAL in the (sub)program
               from which D03EEF is called. Parameters denoted as
               Input must not be changed by this procedure.

           7:  NGX -- INTEGER                                         Input

           8:  NGY -- INTEGER                                         Input
               On entry: the number of interior grid points in the x- and y
               -directions respectively, n  and n . If the seven-diagonal
                                          x      y
               equations are to be solved by D03EDF, then NGX-1 and NGY-1
               should preferably be divisible by as high a power of 2 as
               possible. Constraint: NGX >= 3, NGY >= 3.

           9:  LDA -- INTEGER                                         Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which D03EEF is called.
               Constraint: if only the seven-diagonal equations are
               required, then LDA >= NGX*NGY. If a call to this routine is
               to be followed by a call to D03EDF to solve the seven-
               diagonal linear equations, LDA >= (4*(NGX+1)*(NGY+1))/3.

               Note: this routine only checks the former condition. D03EDF,
               if called, will check the latter condition.

          10:  A(LDA,7) -- DOUBLE PRECISION array                    Output
               On exit: A(i,j), for i=1,2,...,NGX*NGY; j = 1,2,...,7,
               contains the seven-diagonal linear equations produced by the
               discretization described above. If LDA > NGX*NGY, the
               remaining elements are not referenced by the routine, but if
               LDA >= (4*(NGX+1)*(NGY+1))/3 then the array A can be passed
               directly to D03EDF, where these elements are used as
               workspace.

          11:  RHS(LDA) -- DOUBLE PRECISION array                    Output
               On exit: the first NGX*NGY elements contain the right-hand
               sides of the seven-diagonal linear equations produced by the
               discretization described above. If LDA > NGX*NGY, the
               remaining elements are not referenced by the routine, but if
               LDA >= (4*(NGY+1)*(NGY+1))/3 then the array RHS can be
               passed directly to D03EDF, where these elements are used as
               workspace.

          12:  SCHEME -- CHARACTER*1                                  Input
               On entry: the type of approximation to be used for the first
               derivatives which occur in the partial differential
               equation.

               If SCHEME = 'C', then central differences are used.

               If SCHEME = 'U', then upwind differences are used.
               Constraint: SCHEME = 'C' or 'U'.

               Note: generally speaking, if at least one of the
               coefficients multiplying the first derivatives (DELTA or
               EPSLON as returned by PDEF) are large compared with the
               coefficients multiplying the second derivatives, then upwind
               differences may be more appropriate. Upwind differences are
               less accurate than central differences, but may result in
               more rapid convergence for strongly convective equations.
               The easiest test is to try both schemes.

          13:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. Users who are
               unfamiliar with this parameter should refer to the Essential
               Introduction for details.

               On exit: IFAIL = 0 unless the routine detects an error or
               gives a warning (see Section 6).

               For this routine, because the values of output parameters
               may be useful even if IFAIL /=0 on exit, users are
               recommended to set IFAIL to -1 before entry. It is then
               essential to test the value of IFAIL on exit.

          6. Error Indicators and Warnings

          Errors or warnings specified by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry XMIN >= XMAX,

               or       YMIN >= YMAX,

               or       NGX < 3,

               or       NGY < 3,

               or       LDA < NGX*NGY,

               or       SCHEME is not one of 'C' or 'U'.

          IFAIL= 2
               At some point on the boundary there is a derivative in the
               boundary conditions (B /= 0 on return from a BNDY) and there
                                                                     2
                                                                   dd U
               is a non-zero coefficient of the mixed derivative  ------
                                                                  ddxddy
               (BETA /= 0 on return from PDEF).

          IFAIL= 3
               A null boundary has been specified, i.e., at some point both
               A and B are zero on return from a call to BNDY.

          IFAIL= 4
                                                                    2
               The equation is not elliptic, i.e., 4*ALPHA*GAMMA<BETA  after
               a call to PDEF. The discretization has been completed, but
               the convergence of D03EDF cannot be guaranteed.

          IFAIL= 5
               The boundary conditions are purely Neumann (only the
               derivative is specified) and there is, in general, no unique
               solution.

          IFAIL= 6
               The equations were not diagonally dominant. (See Section 3).

          7. Accuracy

          Not applicable.

          8. Further Comments

          If this routine is used as a pre-processor to the multigrid
          routine D03EDF it should be noted that the rate of convergence of
          that routine is strongly dependent upon the number of levels in
          the multigrid scheme, and thus the choice of NGX and NGY is very
          important.

          9. Example

          The program solves the elliptic partial differential equation

                             2     2
                           dd U  dd U   { ddU  ddU}
                           ----+ ----+50{ ---+ ---}=f(x,y)
                              2     2   { ddx  ddy}
                           ddx   ddy

          on the unit square 0<=x, y<=1, with boundary conditions

                ddU
                --- given on x=0 and y=0,
                ddn

               U given on x=1 and y=1.

          The function f(x,y) and the exact form of the boundary conditions
          are derived from the exact solution U(x,y)=sinxsiny.

          The equation is first solved using central differences. Since the
          coefficients of the first derivatives are large, the linear
          equations are not diagonally dominated, and convergence is slow.
          The equation is solved a second time with upwind differences,
          showing that convergence is more rapid, but the solution is less
          accurate.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          D03 -- Partial Differential Equations                      D03FAF
                  D03FAF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          D03FAF solves the Helmholtz equation in Cartesian co-ordinates in
          three dimensions using the standard seven-point finite difference
          approximation. This routine is designed to be particularly
          efficient on vector processors.

          2. Specification

                 SUBROUTINE D03FAF (XS, XF, L, LBDCND, BDXS, BDXF, YS, YF,
                1                   M, MBDCND, BDYS, BDYF, ZS, ZF, N,
                2                   NBDCND, BDZS, BDZF, LAMBDA, LDIMF,
                3                   MDIMF, F, PERTRB, W, LWRK, IFAIL)
                 INTEGER          L, LBDCND, M, MBDCND, N, NBDCND, LDIMF,
                1                 MDIMF, LWRK, IFAIL
                 DOUBLE PRECISION XS, XF, BDXS(MDIMF,N+1), BDXF(MDIMF,N+1),
                1                 YS, YF, BDYS(LDIMF,N+1), BDYF(LDIMF,N+1),
                2                 ZS, ZF, BDZS(LDIMF,M+1), BDZF(LDIMF,M+1),
                3                 LAMBDA, F(LDIMF,MDIMF,N+1), PERTRB, W
                4                 (LWRK)

          3. Description

          D03FAF solves the three-dimensional Helmholtz equation in
          cartesian co-ordinates:

                           2     2     2
                         dd u  dd u  dd u
                         ----+ ----+ ----+(lambda)u=f(x,y,z)
                           2     2     2
                         dd x  dd y  dd z

          This subroutine forms the system of linear equations resulting
          from the standard seven-point finite difference equations, and
          then solves the system using a method based on the fast Fourier
          transform (FFT) described by Swarztrauber [1]. This subroutine is
          based on the routine HW3CRT from FISHPACK (see Swarztrauber and
          Sweet [2]).

          More precisely, the routine replaces all the second derivatives
          by second-order central difference approximations, resulting in a
          block tridiagonal system of linear equations. The equations are
          modified to allow for the prescribed boundary conditions. Either
          the solution or the derivative of the solution may be specified
          on any of the boundaries, or the solution may be specified to be
          periodic in any of the three dimensions. By taking the discrete
          Fourier transform in the x- and y-directions, the equations are
          reduced to sets of tridiagonal systems of equations. The Fourier
          transforms required are computed using the multiple FFT routines
          found in Chapter C06 of the NAG Fortran Library.

          4. References

          [1]   Swarztrauber P N (1984) Fast Poisson Solvers. Studies in
                Numerical Analysis. (ed G H Golub) Mathematical Association
                of America.

          [2]   Swarztrauber P N and Sweet R A (1979) Efficient Fortran
                Subprograms for the Solution of Separable Elliptic Partial
                Differential Equations. ACM Trans. Math. Softw. 5 352--364.

          5. Parameters

           1:  XS -- DOUBLE PRECISION                                 Input
               On entry: the lower bound of the range of x, i.e., XS <= x
               <= XF. Constraint: XS < XF.

           2:  XF -- DOUBLE PRECISION                                 Input
               On entry: the upper bound of the range of x, i.e., XS <= x
               <= XF. Constraint: XS < XF.

           3:  L -- INTEGER                                           Input
               On entry: the number of panels into which the interval
               (XS,XF) is subdivided. Hence, there will be L+1 grid points
               in the x-direction given by x =XS+(i-1)*(delta)x, for
                                            i
               i=1,2,...,L+1, where (delta)x=(XF-XS)/L is the panel width.
               Constraint: L >= 5.

           4:  LBDCND -- INTEGER                                      Input
               On entry: indicates the type of boundary conditions at x =
               XS and x = XF.
               LBDCND = 0
                     if the solution is periodic in x, i.e.,
                     u(XS,y,z)=u(XF,y,z).

               LBDCND = 1
                     if the solution is specified at x = XS and x = XF.

               LBDCND = 2
                     if the solution is specified at x = XS and the
                     derivative of the solution with respect to x is
                     specified at x = XF.

               LBDCND = 3
                     if the derivative of the solution with respect to x is
                     specified at x = XS and x = XF.

               LBDCND = 4
                     if the derivative of the solution with respect to x is
                     specified at x = XS and the solution is specified at x
                     = XF.
                Constraint: 0 <= LBDCND <= 4.

           5:  BDXS(MDIMF,N+1) -- DOUBLE PRECISION array              Input
               On entry: the values of the derivative of the solution with
               respect to x at x = XS. When LBDCND = 3 or 4, BDXS
               (j,k)=u (XS,y ,z ), for j=1,2,...,M+1; k=1,2,...,N+1.
                      x     j  k

               When LBDCND has any other value, BDXS is not referenced.

           6:  BDXF(MDIMF,N+1) -- DOUBLE PRECISION array              Input
               On entry: the values of the derivative of the solution with
               respect to x at x = XF. When LBDCND = 2 or 3, BDXF(j,k) =
               u (XF,y ,z ), for j=1,2,...,M+1; k=1,2,...,N+1.
                x     i  k

               When LBDCND has any other value, BDXF is not referenced.

           7:  YS -- DOUBLE PRECISION                                 Input
               On entry: the lower bound of the range of y, i.e., YS <= y
               <= YF. Constraint: YS < YF.

           8:  YF -- DOUBLE PRECISION                                 Input
               On entry: the upper bound of the range of y, i.e., YS <= y
               <= YF. Constraint: YS < YF.

           9:  M -- INTEGER                                           Input
               On entry: the number of panels into which the interval
               (YS,YF) is subdivided. Hence, there will be M+1 grid points
               in the y-direction given by y  = YS + (j-1)*(delta)y for
                                            j
               j=1,2,...,M+1, where (delta)y=(YF-YS)/M is the panel width.
               Constraint: M >= 5.

          10:  MBDCND -- INTEGER                                      Input
               On entry: indicates the type of boundary conditions at y =
               YS and y = YF.
               MBDCND = 0
                     if the solution is periodic in y, i.e.,
                     u(x,YF,z)=u(x,YS,z).

               MBDCND = 1
                     if the solution is specified at y = YS and y = YF.

               MBDCND = 2
                     if the solution is specified at y = YS and the
                     derivative of the solution with respect to y is
                     specified at y = YF.

               MBDCND = 3
                     if the derivative of the solution with respect to y is
                     specified at y = YS and y = YF.

               MBDCND = 4
                     if the derivative of the solution with respect to y is
                     specified at y = YS and the solution is specified at y
                     = YF.
                Constraint: 0 <= MBDCND <= 4.

          11:  BDYS(LDIMF,N+1) -- DOUBLE PRECISION array              Input
               On entry: the values of the derivative of the solution with
               respect to y at y = YS. When MBDCND = 3 or 4, BDYS
               (i,k)=u (x ,y ,z ), for i=1,2,...,L+1; k=1,2,...,N+1.
                      y  i  s  k

               When MBDCND has any other value, BDYS is not referenced.

          12:  BDYF(LDIMF,N+1) -- DOUBLE PRECISION array              Input
               On entry: the values of the derivative of the solution with
               respect to y at y = YF. When MBDCND = 2 or 3, BDYF
               (i,k)=u (x ,YF,z ), for i=1,2,...,L+1; k=1,2,...,N+1.
                      y  i     k

               When MBDCND has any other value, BDYF is not referenced.

          13:  ZS -- DOUBLE PRECISION                                 Input
               On entry: the lower bound of the range of z, i.e., ZS <= z
               <= ZF. Constraint: ZS < ZF.

          14:  ZF -- DOUBLE PRECISION                                 Input
               On entry: the upper bound of the range of z, i.e., ZS <= z
               <= ZF. Constraint: ZS < ZF.

          15:  N -- INTEGER                                           Input
               On entry: the number of panels into which the interval
               (ZS,ZF) is subdivided. Hence, there will be N+1 grid points
               in the z-direction given by z =ZS+(k-1)*(delta)z, for
                                            k
               k=1,2,...,N+1, where (delta)z=(ZF-ZS)/N is the panel width.
               Constraint: N >= 5.

          16:  NBDCND -- INTEGER                                      Input
               On entry: specifies the type of boundary conditions at z =
               ZS and z = ZF.
               NBDCND = 0
                     if the solution is periodic in z, i.e.,
                     u(x,y,ZF)=u(x,y,ZS).

               NBDCND = 1
                     if the solution is specified at z = ZS and z = ZF.

               NBDCND = 2
                     if the solution is specified at z = ZS and the
                     derivative of the solution with respect to z is
                     specified at z = ZF.

               NBDCND = 3
                     if the derivative of the solution with respect to z is
                     specified at z = ZS and z = ZF.

               NBDCND = 4
                     if the derivative of the solution with respect to z is
                     specified at z = ZS and the solution is specified at z
                     = ZF.
                Constraint: 0 <= NBDCND <= 4.

          17:  BDZS(LDIMF,M+1) -- DOUBLE PRECISION array              Input
               On entry: the values of the derivative of the solution with
               respect to z at z = ZS. When NBDCND = 3 or 4, BDZS
               (i,j)=u (x ,y ,ZS)=u(x,y,z), for i=1,2,...,L+1;
                      z  i  j
               j=1,2,...,M+1.

               When NBDCND has any other value, BDZS is not referenced.

          18:  BDZF(LDIMF,M+1) -- DOUBLE PRECISION array              Input
               On entry: the values of the derivative of the solution with
               respect to z at z = ZF. When NBDCND = 2 or 3, BDZF
               (i,j)=u (x ,y ,ZF)=u(x,y,z), for i=1,2,...,L+1;
                      z  i  j
               j=1,2,...,M+1.

               When NBDCND has any other value, BDZF is not referenced.

          19:  LAMBDA -- DOUBLE PRECISION                             Input
               On entry: the constant (lambda) in the Helmholtz equation.
               For certain positive values of (lambda) a solution to the
               differential equation may not exist, and close to these
               values the solution of the discretized problem will be
               extremely ill-conditioned. If (lambda)>0, then D03FAF will
               set IFAIL to 3, but will still attempt to find a solution.
               However, since in general the values of (lambda) for which
               no solution exists cannot be predicted a priori, the user is
               advised to treat any results computed with (lambda)>0 with
               great caution.

          20:  LDIMF -- INTEGER                                       Input
               On entry:
               the first dimension of the arrays F, BDYS, BDYF, BDZS and
               BDZF as declared in the (sub)program from which D03FAF is
               called.
               Constraint: LDIMF >= L + 1.

          21:  MDIMF -- INTEGER                                       Input
               On entry: the second dimension of the array F and
               the first dimension of the arrays BDXS and BDXF as declared
               in the (sub)program from which D03FAF is called.
               Constraint: MDIMF >= M + 1.

          22:  F(LDIMF,MDIMF,N+1) -- DOUBLE PRECISION array    Input/Output
               On entry: the values of the right-side of the Helmholtz
               equation and boundary values (if any).

               F(i,j,k)=f(x ,y ,z ) i=2,3,...,L, j=2,3,...,M and k
                           i  j  k
               =2,3,...,N.

               On the boundaries F is defined by
               LBDCND    F(1,j,k)  F(L+1,j,k)

               0         f(XS,y ,z )f(XS,y ,z )
                               j  k      j  k

               1         u(XS,y ,z )u(XF,y ,z )
                               j  k      j  k

               2         u(XS,y ,z )f(XF,y ,z )  j=1,2,...,M+1
                               j  k      j  k

               3         f(XS,y ,z )f(XF,y ,z )  k=1,2,...,N+1
                               j  k      j  k

               4         f(XS,y ,z )u(XF,y ,z )
                               j  k      j  k



               MBDCND    F(i,1,k)  F(
                                   i,M+1,k)

               0         f(x ,YS,z )f(x ,YS,z )
                            i     k   i     k

               1         u(x ,YS,z )u(x ,YF,z )
                            i     k   i     k

               2         u(x ,YS,z )f(x ,YF,z )  i=1,2,...,L+1
                            i     k   i     k

               3         f(x ,YS,z )f(x ,YF,z )  k=1,2,...,N+1
                            i     k   i     k

               4         f(x ,YS,z )u(x ,YF,z )
                            i     k   i     k



               NBDCND    F(i,j,1)  F(i,j,N+1
                                   )

               0         f(x ,y ,ZS)f(x ,y ,ZS)
                            i  j      i  j

               1         u(x ,y ,ZS)u(x ,y ,ZF)
                            i  j      i  j

               2         u(x ,y ,ZS)f(x ,y ,ZF)  i=1,2,...,L+1
                            i  j      i  j

               3         f(x ,y ,ZS)f(x ,y ,ZF)  j=1,2,...,M+1
                            i  j      i  j

               4         f(x ,y ,ZS)u(x ,y ,ZF)
                            i  j      i  j
               Note: if the table calls for both the solution u and the
               right-hand side f on a boundary, then the solution must be
               specified. On exit: F contains the solution u(i,j,k) of the
               finite difference approximation for the grid point (
               x ,y ,z ) for i=1,2,...,L+1, j=1,2,...,M+1 and k=1,2,...,N+1.
                i  j  k

          23:  PERTRB -- DOUBLE PRECISION                            Output
               On exit: PERTRB = 0, unless a solution to Poisson's
               equation ((lambda)=0) is required with a combination of
               periodic or derivative boundary conditions (LBDCND, MBDCND
               and NBDCND = 0 or 3). In this case a solution may not exist.
               PERTRB is a constant, calculated and subtracted from the
               array F, which ensures that a solution exists. D03FAF then
               computes this solution, which is a least-squares solution to
               the original approximation. This solution is not unique and
               is unnormalised. The value of PERTRB should be small
               compared to the right-hand side F, otherwise a solution has
               been obtained to an essentially different problem. This
               comparison should always be made to insure that a meaningful
               solution has been obtained.

          24:  W(LWRK) -- DOUBLE PRECISION array                  Workspace

          25:  LWRK -- INTEGER                                        Input
               On entry:
               the dimension of the array W as declared in the (sub)program
               from which D03FAF is called.
               LRWK>=2*(N+1)*max(L,M)+3*L+3*M+4*N+6 is an upper bound on
               the required size of W. If LWRK is too small, the routine
               exits with IFAIL = 2, and if on entry IFAIL = 0 or IFAIL = -
               1, a message is output giving the exact value of LWRK
               required to solve the current problem.

          26:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. Users who are
               unfamiliar with this parameter should refer to the Essential
               Introduction for details.

               On exit: IFAIL = 0 unless the routine detects an error or
               gives a warning (see Section 6).

               For this routine, because the values of output parameters
               may be useful even if IFAIL /=0 on exit, users are
               recommended to set IFAIL to -1 before entry. It is then
               essential to test the value of IFAIL on exit.

          6. Error Indicators and Warnings

          Errors or warnings specified by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry XS >= XF,

               or       L < 5,

               or       LBDCND < 0,

               or       LBDCND > 4,

               or       YS >= YF,

               or       M < 5,

               or       MBDCND < 0,

               or       MBDCND > 4,

               or       ZS >= ZF,

               or       N < 5,

               or       NBDCND < 0,

               or       NBDCND > 4,

               or       LDIMF < L + 1 > 0,

               or       MDIMF < M + 1.

          IFAIL= 2
               On entry LWRK is too small.

          IFAIL= 3
               On entry (lambda) > 0.

          7. Accuracy

          None.

          8. Further Comments

          The execution time is roughly proportional to
          L*M*N*(log L+log M+5), but also depends on input parameters
                    2     2
          LBDCND and MBDCND.

          9. Example

          The example solves the Helmholz equation

                           2     2     2
                         dd u  dd u  dd u
                         ----+ ----+ ----+(lambda)u=f(x,y,z)
                            2     2     2
                         ddx   ddy   ddz

                                               (pi)
          for (x,y,z)is in [0,1]*[0,2(pi)]*[0, ----] where (lambda)=-2, and
                                                2
          f(x,y,z) is derived from the exact solution

                                          4
                                u(x,y,z)=x sin(y)cos(z).

          The equation is subject to the following boundary conditions,
          again derived from the exact solution given above.

               u(0,y,z) and u(1,y,z) are prescribed (i.e., LBDCND = 1).

               u(x,0,z)=u(x,2(pi),z) (i.e., MBDCND = 0).

                                    (pi)
               u(x,y,0) and u (x,y, ----) are prescribed (i.e. NBDCND = 2).
                             x       2

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

